Bug 28848 - OpenAPI version should be a string
Summary: OpenAPI version should be a string
Status: RESOLVED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: REST API (show other bugs)
Version: master
Hardware: All All
: P5 - low normal (vote)
Assignee: Tomás Cohen Arazi
QA Contact: Martin Renvoize
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2021-08-12 13:29 UTC by Tomás Cohen Arazi
Modified: 2021-12-13 21:14 UTC (History)
2 users (show)

See Also:
Change sponsored?: ---
Patch complexity: ---
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:
21.11.00


Attachments
Bug 28848: Make sure the 'swagger' attribute is a string (658 bytes, patch)
2021-08-12 14:15 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 28848: Make sure the 'swagger' attribute is a string (705 bytes, patch)
2021-08-12 20:05 UTC, David Nind
Details | Diff | Splinter Review
Bug 28848: Make sure the 'swagger' attribute is a string (769 bytes, patch)
2021-08-13 12:31 UTC, Martin Renvoize
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Tomás Cohen Arazi 2021-08-12 13:29:55 UTC
As mentioned explicitly in the OpenAPI 2.0 spec, the 'swagger' attribute needs to be a 'string':

"""
Required. Specifies the Swagger Specification version being used. It can be used by the Swagger UI and other clients to interpret the API listing. The value MUST be "2.0".
"""

Out stack doesn't take that into  account, but some validator will take our spec as having a number instead.

A fix should be backported to all stable releases so we can use newer versions of redoc for the API docs.
Comment 1 Tomás Cohen Arazi 2021-08-12 14:15:44 UTC
Created attachment 123815 [details] [review]
Bug 28848: Make sure the 'swagger' attribute is a string

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 2 Tomás Cohen Arazi 2021-08-12 14:30:48 UTC
I'm not sure how this should be tested. Just see "2.0" is wrapped in double quotes, which is what the spec expects as mentioned.
Comment 3 David Nind 2021-08-12 20:05:26 UTC
Created attachment 123818 [details] [review]
Bug 28848: Make sure the 'swagger' attribute is a string

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: David Nind <david@davidnind.com>
Comment 4 David Nind 2021-08-12 20:06:55 UTC
Testing notes (koha-testing-docker):

1. Go to https://editor.swagger.io/
2. Load the api/v1/swagger/swagger.yaml file (File > Import file)
3. You should get this message: 
    Unable to render this definition
    The provided definition does not specify a valid version field.
    Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).
4. Apply the patch
5. Repeat steps 1-2
6. The file should now load
Comment 5 Martin Renvoize 2021-08-13 12:31:21 UTC
Created attachment 123823 [details] [review]
Bug 28848: Make sure the 'swagger' attribute is a string

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: David Nind <david@davidnind.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 6 Martin Renvoize 2021-08-13 12:33:25 UTC
Obvious fix.. PQA
Comment 7 Jonathan Druart 2021-08-16 10:05:30 UTC
Pushed to master for 21.11, thanks to everybody involved!