Bug 29620

Summary: Move the OpenAPI spec to YAML format
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: enhancement    
Priority: P5 - low CC: andrewfh, david, fridolin.somers, jonathan.druart, kyle, martin.renvoize
Version: unspecified   
Hardware: All   
OS: All   
Change sponsored?: --- Patch complexity: Trivial patch
Documentation contact: Documentation submission:
Text to go in the release notes:
This enhancement moves all the Koha REST API specification from json to YAML format. It also corrects two named parameters incorrectly in camelCase to sanake_case (fundidPathParam => fund_id_pp, vendoridPathParam => vendor_id_pp).
Version(s) released in:
22.05.00,21.11.01
Bug Depends on: 29072, 29593    
Bug Blocks: 28020    
Attachments: Bug 29620: Move the OpenAPI spec to YAML format
Bug 29620: (follow-up) Rename remaining old-style parameters
Bug 29620: Move the OpenAPI spec to YAML format
Bug 29620: (follow-up) Rename remaining old-style parameters

Description Tomás Cohen Arazi 2021-12-02 11:41:23 UTC
Work has started on new routes and the reference /cities spec, we should do it in one run on this bug.
Comment 1 Tomás Cohen Arazi 2021-12-02 15:31:03 UTC
Created attachment 128173 [details] [review]
Bug 29620: Move the OpenAPI spec to YAML format

This patch moves all the REST API spec pieces into YAML.

To test:
1. Run:
   $ kshell
  k$ prove t/db_dependent/api/v1/*
=> SUCCESS: Tests pass
2. Apply this patch
3. Repeat 1
=> SUCCESS: Tests still pass!
4. Sign off :-D

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 2 Tomás Cohen Arazi 2021-12-02 15:31:10 UTC
Created attachment 128174 [details] [review]
Bug 29620: (follow-up) Rename remaining old-style parameters

The first routes we added named parameters in camelCase. We moved to
snake_case really fast, but there are two that were kept by mistake.

This patch fixes them.

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 3 Tomás Cohen Arazi 2021-12-02 15:32:03 UTC
If we agree with this, it should be pushed early this cycle. To allow people to produce their patches on top of it.
Comment 4 Martin Renvoize 2021-12-03 12:16:02 UTC
Created attachment 128211 [details] [review]
Bug 29620: Move the OpenAPI spec to YAML format

This patch moves all the REST API spec pieces into YAML.

To test:
1. Run:
   $ kshell
  k$ prove t/db_dependent/api/v1/*
=> SUCCESS: Tests pass
2. Apply this patch
3. Repeat 1
=> SUCCESS: Tests still pass!
4. Sign off :-D

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 5 Martin Renvoize 2021-12-03 12:16:08 UTC
Created attachment 128212 [details] [review]
Bug 29620: (follow-up) Rename remaining old-style parameters

The first routes we added named parameters in camelCase. We moved to
snake_case really fast, but there are two that were kept by mistake.

This patch fixes them.

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 6 Martin Renvoize 2021-12-03 12:17:12 UTC
Go Go Go... this is a no brainer to me.. all works, no breaking changes, just improves readability and makes it easier going forward.

Going straight for QA.. Passed!
Comment 7 Fridolin Somers 2021-12-07 22:33:19 UTC
Pushed to master for 22.05, thanks to everybody involved 🦄
Comment 8 Tomás Cohen Arazi 2021-12-08 00:59:42 UTC
(In reply to Fridolin Somers from comment #7)
> Pushed to master for 22.05, thanks to everybody involved 🦄

Thank you. We need to have documentation people add more info now in Markdown
Comment 9 Kyle M Hall 2021-12-10 12:29:32 UTC
Pushed to 21.11.x for 21.11.01
Comment 10 Kyle M Hall 2021-12-10 12:30:52 UTC
I anticipate we may need to backport patches related to these files in 21.11.x branch. It makes sense to backport these changes for that reason.
Comment 11 Andrew Fuerste-Henry 2021-12-17 19:44:48 UTC
Not backporting to 21.05 due to missing dependencies.