Koha-community/Koha
13
7
Fork 0
Code Issues Releases Wiki Activity

Bug 34387: Improve API docs naming consistency

Browse source 
This patch aims to make our API docs be more consistent.
It addresses two particular things:

* There's no consistency on the `tags` used across the spec, and not all
  of them are correctly described and have an `x-displayName` entry.
  More on this later.
* This are not sorted either by some for of grouping, or at least
  alphabetically.

For the former, I did my best trying to harmonize (specially on the ERM
front) with what we do in the rest of the use cases.

For the latter, I opted for sorting everything alphabetically, as a
first step. Hoping someone else could work on grouping things.

To test (ON YOUR HOST MACHINE):
1. On current master run:
   $ cd api/v1/swagger
   $ docker run --rm -v $(pwd):/api --workdir /api redocly/cli \
           build-docs swagger.yaml --output index.html
=> SUCCESS: It doesn't break or anything
2. Open your browser, open the generated api/v1/swagger/index.html file
=> FAIL: The left column has
         * several lower case entries
         * not everything is correctly grouped (ERM? packages?)
         * Things are not sorted. There's an attempt but looks messy
3. Apply this patch
4. Repeat 1 and 2
=> SUCCESS: Things look much better!
5. Sign off :-D

CAVEAT1: I'm not sure why, but import_batches doesn't work. Ideas are
welcome, I'll keep looking for fixes.
CAVEAT2: I don't have enough eHoldings background to weight in, but I
feel like 'ERM eHoldings packages' could just be 'ERM packages'.
Follw-up patches with better ideas are welcome.
CAVEAT3: Patron credits, debits, balance... They could all go in to
'Patrons accounts' or similar. Open to ideas.
CAVEAT4: Old redocly didn't support mapping an endpoint to more than one
target section. Something to explore if we want (for example) to reach
'credits' through the 'Patrons' section but also from 'Accounting'.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
This commit is contained in:
Tomás Cohen Arazi 2023-07-25 15:57:58 -03:00 committed by Fridolin Somers
parent 3756a98a2d
commit 355d7dc52c
12 changed files with 75 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
api/v1/swagger/paths/erm_agreements.yaml
View file

@ -4,7 +4,7 @@
x-mojo-to: ERM::Agreements#list
operationId: listErmAgreements
tags:
- agreement
- erm_agreements
summary: List agreements
produces:
- application/json
@ -109,7 +109,7 @@
x-mojo-to: ERM::Agreements#add
operationId: addErmAgreements
tags:
- agreement
- erm_agreements
summary: Add agreement
consumes:
- application/json
@ -170,7 +170,7 @@
x-mojo-to: ERM::Agreements#get
operationId: getErmAgreements
tags:
- agreement
- erm_agreements
summary: Get agreement
produces:
- application/json
@ -232,7 +232,7 @@
x-mojo-to: ERM::Agreements#update
operationId: updateErmAgreements
tags:
- agreement
- erm_agreements
summary: Update agreement
consumes:
- application/json
@ -303,7 +303,7 @@
x-mojo-to: ERM::Agreements#delete
operationId: deleteErmAgreements
tags:
- agreement
- erm_agreements
summary: Delete agreement
produces:
- application/json

2
api/v1/swagger/paths/erm_documents.yaml
View file

@ -4,7 +4,7 @@
x-mojo-to: ERM::Documents#get
operationId: downloadErmDocument
tags:
- document
- erm_documents
summary: Download erm document
produces:
- application/octet-stream

12
api/v1/swagger/paths/erm_eholdings_packages.yaml
View file

@ -4,7 +4,7 @@
x-mojo-to: ERM::EHoldings::Packages#list
operationId: listErmEHoldingsPackages
tags:
- eHoldings package
- erm_eholdings_packages
summary: List packages
produces:
- application/json
@ -106,7 +106,7 @@
x-mojo-to: ERM::EHoldings::Packages#add
operationId: addErmEHoldingsPackages
tags:
- eHoldings package
- erm_eholdings_packages
summary: Add package
consumes:
- application/json
@ -168,7 +168,7 @@
x-mojo-to: ERM::EHoldings::Packages#get
operationId: getErmEHoldingsPackages
tags:
- package
- erm_eholdings_packages
summary: Get eHoldings package
produces:
- application/json
@ -227,7 +227,7 @@
x-mojo-to: ERM::EHoldings::Packages#update
operationId: updateErmEHoldingsPackages
tags:
- package
- erm_eholdings_packages
summary: Update eHoldings package
consumes:
- application/json
@ -296,7 +296,7 @@
x-mojo-to: ERM::EHoldings::Packages#delete
operationId: deleteErmEHoldingsPackages
tags:
- package
- erm_eholdings_packages
summary: Delete eHoldings package
produces:
- application/json
@ -347,7 +347,7 @@
x-mojo-to: ERM::EHoldings::Packages#edit
operationId: editErmEHoldingsPackages
tags:
- eholdings
- erm_eholdings_packages
summary: Edit a package
produces:
- application/json

2
api/v1/swagger/paths/erm_eholdings_packages_resources.yaml
View file

@ -4,7 +4,7 @@
x-mojo-to: ERM::EHoldings::Resources#list
operationId: listErmEHoldingsPackagesResources
tags:
- eholdings
- erm_eholdings_packages
summary: List eholdings resources
produces:
- application/json

6
api/v1/swagger/paths/erm_eholdings_resources.yaml
View file

@ -4,7 +4,7 @@
x-mojo-to: ERM::EHoldings::Resources#list
operationId: listErmEHoldingsResources
tags:
- eholdings
- erm_eholdings_resources
summary: List eholdings resources
produces:
- application/json
@ -84,7 +84,7 @@
x-mojo-to: ERM::EHoldings::Resources#get
operationId: getErmEHoldingsResources
tags:
- eholdings
- erm_eholdings_resources
summary: Get resources
produces:
- application/json
@ -142,7 +142,7 @@
x-mojo-to: ERM::EHoldings::Resources#edit
operationId: editErmEHoldingsResources
tags:
- eholdings
- erm_eholdings_resources
summary: Edit a resource
produces:
- application/json

12
api/v1/swagger/paths/erm_eholdings_titles.yaml
View file

@ -4,7 +4,7 @@
x-mojo-to: ERM::EHoldings::Titles#list
operationId: listErmEHoldingsTitles
tags:
- eholdings
- erm_eholdings_titles
summary: List eholdings titles
produces:
- application/json
@ -193,7 +193,7 @@
x-mojo-to: ERM::EHoldings::Titles#add
operationId: addErmEHoldingsTitles
tags:
- eholdings
- erm_eholdings_titles
summary: Add eholding
consumes:
- application/json
@ -255,7 +255,7 @@
x-mojo-to: ERM::EHoldings::Titles#get
operationId: getErmEHoldingsTitles
tags:
- eholdings
- erm_eholdings_titles
summary: Get titles
produces:
- application/json
@ -312,7 +312,7 @@
x-mojo-to: ERM::EHoldings::Titles#update
operationId: updateErmEHoldingsTitles
tags:
- eholdings
- erm_eholdings_titles
summary: Update titles
consumes:
- application/json
@ -381,7 +381,7 @@
x-mojo-to: ERM::EHoldings::Titles#delete
operationId: deleteErmEHoldingsTitles
tags:
- eholdings
- erm_eholdings_titles
summary: Delete eHolding title
produces:
- application/json
@ -433,7 +433,7 @@
x-mojo-to: ERM::EHoldings::Titles#import_from_list
operationId: importErmEHoldingsTitles
tags:
- eholdings
- erm_eholdings_titles
summary: Import local titles
consumes:
- application/json

2
api/v1/swagger/paths/erm_eholdings_titles_resources.yaml
View file

@ -4,7 +4,7 @@
x-mojo-to: ERM::EHoldings::Resources#list
operationId: listErmEHoldingsTitlesResources
tags:
- eholdings
- erm_eholdings_titles
summary: List eholdings resources
produces:
- application/json

10
api/v1/swagger/paths/erm_licenses.yaml
View file

@ -4,7 +4,7 @@
x-mojo-to: ERM::Licenses#list
operationId: listErmLicenses
tags:
- license
- erm_licences
summary: List licenses for agreements
produces:
- application/json
@ -92,7 +92,7 @@
x-mojo-to: ERM::Licenses#add
operationId: addERMLicenses
tags:
- license
- erm_licences
summary: Add license
consumes:
- application/json
@ -153,7 +153,7 @@
x-mojo-to: ERM::Licenses#get
operationId: getERMlicense
tags:
- license
- erm_licences
summary: get license
produces:
- application/json
@ -207,7 +207,7 @@
x-mojo-to: ERM::Licenses#update
operationId: updateERMlicenses
tags:
- license
- erm_licences
summary: update license
consumes:
- application/json
@ -275,7 +275,7 @@
x-mojo-to: ERM::Licenses#delete
operationId: deleteERMlicenses
tags:
- license
- erm_licences
summary: Delete license
produces:
- application/json

2
api/v1/swagger/paths/erm_users.yaml
View file

@ -6,7 +6,7 @@
description: This resource returns a list of patron allowed to be users of the ERM module
summary: List possibe users for ERM
tags:
- ERM
- erm_users
parameters:
- $ref: "../swagger.yaml#/parameters/match"
- $ref: "../swagger.yaml#/parameters/order_by"

2
api/v1/swagger/paths/patrons_account.yaml
View file

@ -48,7 +48,6 @@
operationId: listPatronCredits
tags:
- patrons
- credits
summary: List patron credits
produces:
- application/json
@ -137,7 +136,6 @@
operationId: listPatronDebits
tags:
- patrons
- debits
summary: List patron debits
produces:
- application/json

2
api/v1/swagger/paths/search_filters.yaml
View file

@ -165,7 +165,7 @@
x-mojo-to: SearchFilter#delete
operationId: deleteSearchFilter
tags:
- macros
- search_filters
summary: Delete search filter
parameters:
- $ref: "../swagger.yaml#/parameters/search_filter_id_pp"

57
api/v1/swagger/swagger.yaml
View file

@ -765,15 +765,18 @@ info:
context; If it is not included in the request, then the request context
will default to using your api comsumer"s assigned home library.
tags:
- description: "Handle two factor authentication flows\n"
name: 2fa
x-displayName: Two factor authentication
- description: "Manage article requests\n"
name: article_requests
x-displayName: Article requests
- description: "Manage identity providers\n"
name: identity_providers
x-displayName: Identity providers
- description: "Manage authorised value categories\n"
name: authorised_value_categories
x-displayName: Authorised value categories
- description: "Manage authorised values\n"
name: authorised_values
x-displayName: Authorised values
- description: "Manage batch import profiles\n"
name: batch_import_profiles
x-displayName: Batch import profiles
- description: "Manage baskets for the acquisitions module\n"
name: baskets
x-displayName: Baskets
@ -798,12 +801,36 @@ tags:
- description: "Manage patron clubs\n"
name: clubs
x-displayName: Clubs
- description: "Manage ERM agreements\n"
name: erm_agreements
x-displayName: ERM agreements
- description: "Manage ERM docuemnts\n"
name: erm_documents
x-displayName: ERM documents
- description: "Manage ERM eHoldings packages\n"
name: erm_eholdings_packages
x-displayName: ERM eHoldings packages
- description: "Manage ERM eHoldings resources\n"
name: erm_eholdings_resources
x-displayName: ERM eHoldings resources
- description: "Manage ERM eHoldings titles\n"
name: erm_eholdings_titles
x-displayName: ERM eHoldings titles
- description: "Manage ERM licences\n"
name: erm_licences
x-displayName: ERM licences
- description: "Manage ERM users\n"
name: erm_users
x-displayName: ERM users
- description: "Manage funds for the acquisitions module\n"
name: funds
x-displayName: Funds
- description: "Manage holds\n"
name: holds
x-displayName: Holds
- description: "Manage identity providers\n"
name: identity_providers
x-displayName: Identity providers
- description: "Manage ILL module backends\n"
name: ill_backends
x-displayName: ILL backends
@ -837,6 +864,9 @@ tags:
- description: "Manage patrons\n"
name: patrons
x-displayName: Patrons
- description: "Manage purchase suggestions\n"
name: suggestions
x-displayName: Purchase suggestions
- description: "Manage quotes\n"
name: quotes
x-displayName: Quotes
@ -846,18 +876,21 @@ tags:
- description: "Manage rotas\n"
name: rotas
x-displayName: Rotas
- description: "Manage search filters"
name: search_filters
x-displayName: Search filters
- description: "Manage SMTP servers configurations\n"
name: smtp_servers
x-displayName: SMTP servers
- description: "Manage tickets\n"
name: tickets
x-displayName: Tickets
- description: "Manage transfer limits\n"
name: transfer
x-displayName: Transfer limits
- description: "Manage purchase suggestions\n"
name: suggestions
x-displayName: Purchase suggestions
- description: "Handle two factor authentication flows\n"
name: 2fa
x-displayName: Two factor authentication
- description: "Manage vendors for the acquisitions module\n"
name: vendors
x-displayName: Vendors
- description: "Manage batch import profiles\n"
name: batch_import_profiles
x-displayName: Batch import profiles