Bug 36565 - Fix API docs inconsistencies
Summary: Fix API docs inconsistencies
Status: Pushed to main
Alias: None
Product: Koha
Classification: Unclassified
Component: REST API (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement (vote)
Assignee: Tomás Cohen Arazi
QA Contact: Martin Renvoize
URL:
Keywords:
Depends on: 29002 30708 33036 22440
Blocks:
  Show dependency treegraph
 
Reported: 2024-04-10 08:11 UTC by Tomás Cohen Arazi
Modified: 2024-04-29 07:42 UTC (History)
3 users (show)

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


Attachments
Bug 36565: Unit tests (4.70 KB, patch)
2024-04-10 12:08 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: Bookings API docs fixes (bug 29002 follow-up) (858 bytes, patch)
2024-04-10 12:08 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: ILL requests API docs fixes (bug 22440 follow-up) (822 bytes, patch)
2024-04-10 12:08 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: Biblio merge API docs fixes (bug 33036 follow-up) (826 bytes, patch)
2024-04-10 12:08 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: Preservation module API docs fixes (bug 30708 follow-up) (7.07 KB, patch)
2024-04-10 12:08 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: EDI files API docs fixes (bug 30070 follow-up) (1.40 KB, patch)
2024-04-10 12:08 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: Unit tests (4.74 KB, patch)
2024-04-11 01:16 UTC, David Nind
Details | Diff | Splinter Review
Bug 36565: Bookings API docs fixes (bug 29002 follow-up) (904 bytes, patch)
2024-04-11 01:16 UTC, David Nind
Details | Diff | Splinter Review
Bug 36565: ILL requests API docs fixes (bug 22440 follow-up) (868 bytes, patch)
2024-04-11 01:17 UTC, David Nind
Details | Diff | Splinter Review
Bug 36565: Biblio merge API docs fixes (bug 33036 follow-up) (872 bytes, patch)
2024-04-11 01:17 UTC, David Nind
Details | Diff | Splinter Review
Bug 36565: Preservation module API docs fixes (bug 30708 follow-up) (7.11 KB, patch)
2024-04-11 01:17 UTC, David Nind
Details | Diff | Splinter Review
Bug 36565: EDI files API docs fixes (bug 30070 follow-up) (1.45 KB, patch)
2024-04-11 01:17 UTC, David Nind
Details | Diff | Splinter Review
Bug 36565: Unit tests (4.81 KB, patch)
2024-04-11 05:46 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 36565: Bookings API docs fixes (bug 29002 follow-up) (971 bytes, patch)
2024-04-11 05:46 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 36565: ILL requests API docs fixes (bug 22440 follow-up) (935 bytes, patch)
2024-04-11 05:46 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 36565: Biblio merge API docs fixes (bug 33036 follow-up) (939 bytes, patch)
2024-04-11 05:46 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 36565: Preservation module API docs fixes (bug 30708 follow-up) (7.18 KB, patch)
2024-04-11 05:46 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 36565: EDI files API docs fixes (bug 30070 follow-up) (1.51 KB, patch)
2024-04-11 05:46 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 36565: Unit tests (4.81 KB, patch)
2024-04-26 21:04 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: Bookings API docs fixes (bug 29002 follow-up) (978 bytes, patch)
2024-04-26 21:04 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: ILL requests API docs fixes (bug 22440 follow-up) (937 bytes, patch)
2024-04-26 21:04 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: Biblio merge API docs fixes (bug 33036 follow-up) (939 bytes, patch)
2024-04-26 21:04 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: Preservation module API docs fixes (bug 30708 follow-up) (7.18 KB, patch)
2024-04-26 21:04 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 36565: EDI files API docs fixes (bug 30070 follow-up) (1.95 KB, patch)
2024-04-26 21:04 UTC, Tomás Cohen Arazi
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 2024-04-10 08:11:59 UTC
When you look at https://api.koha-community.org you will notice some categories on the left-side column are not tidy (lower case, similar to other entries but slightly different, etc).

I open this bug to address it.
Comment 1 Tomás Cohen Arazi 2024-04-10 12:08:05 UTC
Created attachment 164612 [details] [review]
Bug 36565: Unit tests

This patch introduces tests on the OpenAPI spec so that all tags used in
path definitions have their corresponding entry at the top level 'tags'
section.

This it important for correctly rendering the API documentation.

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 2 Tomás Cohen Arazi 2024-04-10 12:08:08 UTC
Created attachment 164613 [details] [review]
Bug 36565: Bookings API docs fixes (bug 29002 follow-up)

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 3 Tomás Cohen Arazi 2024-04-10 12:08:10 UTC
Created attachment 164614 [details] [review]
Bug 36565: ILL requests API docs fixes (bug 22440 follow-up)

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 4 Tomás Cohen Arazi 2024-04-10 12:08:12 UTC
Created attachment 164615 [details] [review]
Bug 36565: Biblio merge API docs fixes (bug 33036 follow-up)

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 5 Tomás Cohen Arazi 2024-04-10 12:08:14 UTC
Created attachment 164616 [details] [review]
Bug 36565: Preservation module API docs fixes (bug 30708 follow-up)

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 6 Tomás Cohen Arazi 2024-04-10 12:08:16 UTC
Created attachment 164617 [details] [review]
Bug 36565: EDI files API docs fixes (bug 30070 follow-up)

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 7 Tomás Cohen Arazi 2024-04-10 12:10:08 UTC
To test:
1. Apply the tests patch
2. Run:
   $ ktd --shell
  k$ prove xt/api.t
=> FAIL: Tests fail! We have spec issues!
3. Apply the rest of the patches
4. Repeat 2
=> SUCCESS: Tests pass!
5. Sign off :-D
Comment 8 Tomás Cohen Arazi 2024-04-10 12:11:30 UTC
I submitted a patch for each dependency bug, because I don't want to track where each was released, and this way it can be backported where appropriate.
Comment 9 David Nind 2024-04-11 01:16:56 UTC
Created attachment 164642 [details] [review]
Bug 36565: Unit tests

This patch introduces tests on the OpenAPI spec so that all tags used in
path definitions have their corresponding entry at the top level 'tags'
section.

This it important for correctly rendering the API documentation.

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: David Nind <david@davidnind.com>
Comment 10 David Nind 2024-04-11 01:16:58 UTC
Created attachment 164643 [details] [review]
Bug 36565: Bookings API docs fixes (bug 29002 follow-up)

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: David Nind <david@davidnind.com>
Comment 11 David Nind 2024-04-11 01:17:01 UTC
Created attachment 164644 [details] [review]
Bug 36565: ILL requests API docs fixes (bug 22440 follow-up)

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: David Nind <david@davidnind.com>
Comment 12 David Nind 2024-04-11 01:17:04 UTC
Created attachment 164645 [details] [review]
Bug 36565: Biblio merge API docs fixes (bug 33036 follow-up)

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: David Nind <david@davidnind.com>
Comment 13 David Nind 2024-04-11 01:17:06 UTC
Created attachment 164646 [details] [review]
Bug 36565: Preservation module API docs fixes (bug 30708 follow-up)

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: David Nind <david@davidnind.com>
Comment 14 David Nind 2024-04-11 01:17:09 UTC
Created attachment 164647 [details] [review]
Bug 36565: EDI files API docs fixes (bug 30070 follow-up)

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: David Nind <david@davidnind.com>
Comment 15 Martin Renvoize 2024-04-11 05:46:08 UTC
Created attachment 164648 [details] [review]
Bug 36565: Unit tests

This patch introduces tests on the OpenAPI spec so that all tags used in
path definitions have their corresponding entry at the top level 'tags'
section.

This it important for correctly rendering the API documentation.

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 16 Martin Renvoize 2024-04-11 05:46:11 UTC
Created attachment 164649 [details] [review]
Bug 36565: Bookings API docs fixes (bug 29002 follow-up)

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 17 Martin Renvoize 2024-04-11 05:46:14 UTC
Created attachment 164650 [details] [review]
Bug 36565: ILL requests API docs fixes (bug 22440 follow-up)

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 18 Martin Renvoize 2024-04-11 05:46:17 UTC
Created attachment 164651 [details] [review]
Bug 36565: Biblio merge API docs fixes (bug 33036 follow-up)

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 19 Martin Renvoize 2024-04-11 05:46:21 UTC
Created attachment 164652 [details] [review]
Bug 36565: Preservation module API docs fixes (bug 30708 follow-up)

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 20 Martin Renvoize 2024-04-11 05:46:24 UTC
Created attachment 164653 [details] [review]
Bug 36565: EDI files API docs fixes (bug 30070 follow-up)

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 21 Martin Renvoize 2024-04-11 05:47:18 UTC
Thanks for the cleanup work here Tomas, and apologies it seems I was guilty of introducing a few of the issues.

Great to see a unit test to help prevent these in the future.

Passing QA
Comment 22 Katrin Fischer 2024-04-26 16:03:02 UTC
I fixed the first conflict, but got stuck on the second - can you please rebase?

Applying: Bug 36565: Bookings API docs fixes (bug 29002 follow-up)
Applying: Bug 36565: ILL requests API docs fixes (bug 22440 follow-up)
Using index info to reconstruct a base tree...
M	api/v1/swagger/paths/ill_requests.yaml
Falling back to patching base and 3-way merge...
Auto-merging api/v1/swagger/paths/ill_requests.yaml
Applying: Bug 36565: Biblio merge API docs fixes (bug 33036 follow-up)
Applying: Bug 36565: Preservation module API docs fixes (bug 30708 follow-up)
Applying: Bug 36565: EDI files API docs fixes (bug 30070 follow-up)
error: sha1 information is lacking or useless (api/v1/swagger/swagger.yaml).
error: could not build fake ancestor
Patch failed at 0001 Bug 36565: EDI files API docs fixes (bug 30070 follow-up)
hint: Use 'git am --show-current-patch=diff' to see the failed patch
When you have resolved this problem run "git bz apply --continue".
If you would prefer to skip this patch, instead run "git bz apply --skip".
To restore the original branch and stop patching run "git bz apply --abort".
Patch left in /tmp/Bug-36565-EDI-files-API-docs-fixes-bug-30070-follo-dncuei9u.patch
Comment 23 Tomás Cohen Arazi 2024-04-26 21:04:35 UTC
Created attachment 165698 [details] [review]
Bug 36565: Unit tests

This patch introduces tests on the OpenAPI spec so that all tags used in
path definitions have their corresponding entry at the top level 'tags'
section.

This it important for correctly rendering the API documentation.

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 24 Tomás Cohen Arazi 2024-04-26 21:04:37 UTC
Created attachment 165699 [details] [review]
Bug 36565: Bookings API docs fixes (bug 29002 follow-up)

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 25 Tomás Cohen Arazi 2024-04-26 21:04:40 UTC
Created attachment 165700 [details] [review]
Bug 36565: ILL requests API docs fixes (bug 22440 follow-up)

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 26 Tomás Cohen Arazi 2024-04-26 21:04:43 UTC
Created attachment 165701 [details] [review]
Bug 36565: Biblio merge API docs fixes (bug 33036 follow-up)

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 27 Tomás Cohen Arazi 2024-04-26 21:04:45 UTC
Created attachment 165702 [details] [review]
Bug 36565: Preservation module API docs fixes (bug 30708 follow-up)

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 28 Tomás Cohen Arazi 2024-04-26 21:04:48 UTC
Created attachment 165703 [details] [review]
Bug 36565: EDI files API docs fixes (bug 30070 follow-up)

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 29 Katrin Fischer 2024-04-29 06:53:17 UTC
Thanks for the quick rebase :)

Could we have a test plan to see the changes in action? (not blocker) I managed in the past, but it might be good to have it available somewhere.
Comment 30 Katrin Fischer 2024-04-29 07:42:13 UTC
Pushed for 24.05!

Well done everyone, thank you!