Bug 28848

Summary: OpenAPI version should be a string
Product: Koha Reporter: Tomás Cohen Arazi <tomascohen>
Component: REST APIAssignee: Tomás Cohen Arazi <tomascohen>
Status: CLOSED FIXED QA Contact: Martin Renvoize <martin.renvoize>
Severity: normal    
Priority: P5 - low CC: david, martin.renvoize
Version: Main   
Hardware: All   
OS: All   
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
Bug 28848: Make sure the 'swagger' attribute is a string
Bug 28848: Make sure the 'swagger' attribute is a string

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!