Bugzilla – Attachment 154087 Details for
Bug 34387
API docs tags missing descriptions
Home
|
New
|
Browse
|
Search
|
[?]
|
Reports
|
Help
|
New Account
|
Log In
[x]
|
Forgot Password
Login:
[x]
[patch]
[23.05.x] Bug 34387: Improve API docs naming consistency
2305x-Bug-34387-Improve-API-docs-naming-consistenc.patch (text/plain), 16.48 KB, created by
Tomás Cohen Arazi (tcohen)
on 2023-07-31 12:44:34 UTC
(
hide
)
Description:
[23.05.x] Bug 34387: Improve API docs naming consistency
Filename:
MIME Type:
Creator:
Tomás Cohen Arazi (tcohen)
Created:
2023-07-31 12:44:34 UTC
Size:
16.48 KB
patch
obsolete
>From 60209d7b660ad92f63de9cce33412e56eeb3bf24 Mon Sep 17 00:00:00 2001 >From: Tomas Cohen Arazi <tomascohen@theke.io> >Date: Tue, 25 Jul 2023 15:57:58 -0300 >Subject: [PATCH] [23.05.x] Bug 34387: Improve API docs naming consistency > >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> >--- > api/v1/swagger/paths/erm_agreements.yaml | 10 ++-- > api/v1/swagger/paths/erm_documents.yaml | 2 +- > .../swagger/paths/erm_eholdings_packages.yaml | 12 ++-- > .../erm_eholdings_packages_resources.yaml | 2 +- > .../paths/erm_eholdings_resources.yaml | 6 +- > .../swagger/paths/erm_eholdings_titles.yaml | 12 ++-- > .../paths/erm_eholdings_titles_resources.yaml | 2 +- > api/v1/swagger/paths/erm_licenses.yaml | 10 ++-- > api/v1/swagger/paths/erm_users.yaml | 2 +- > api/v1/swagger/paths/patrons_account.yaml | 2 - > api/v1/swagger/paths/search_filters.yaml | 2 +- > api/v1/swagger/swagger.yaml | 57 +++++++++++++++---- > 12 files changed, 75 insertions(+), 44 deletions(-) > >diff --git a/api/v1/swagger/paths/erm_agreements.yaml b/api/v1/swagger/paths/erm_agreements.yaml >index 289bc36a130..655fed2e3a6 100644 >--- a/api/v1/swagger/paths/erm_agreements.yaml >+++ b/api/v1/swagger/paths/erm_agreements.yaml >@@ -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 >diff --git a/api/v1/swagger/paths/erm_documents.yaml b/api/v1/swagger/paths/erm_documents.yaml >index 31ea1354138..80be3279b3c 100644 >--- a/api/v1/swagger/paths/erm_documents.yaml >+++ b/api/v1/swagger/paths/erm_documents.yaml >@@ -4,7 +4,7 @@ > x-mojo-to: ERM::Documents#get > operationId: downloadErmDocument > tags: >- - document >+ - erm_documents > summary: Download erm document > produces: > - application/octet-stream >diff --git a/api/v1/swagger/paths/erm_eholdings_packages.yaml b/api/v1/swagger/paths/erm_eholdings_packages.yaml >index 51899e33162..0237e6fcfb8 100644 >--- a/api/v1/swagger/paths/erm_eholdings_packages.yaml >+++ b/api/v1/swagger/paths/erm_eholdings_packages.yaml >@@ -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 >diff --git a/api/v1/swagger/paths/erm_eholdings_packages_resources.yaml b/api/v1/swagger/paths/erm_eholdings_packages_resources.yaml >index 696f4958572..8c3ead3e4a0 100644 >--- a/api/v1/swagger/paths/erm_eholdings_packages_resources.yaml >+++ b/api/v1/swagger/paths/erm_eholdings_packages_resources.yaml >@@ -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 >diff --git a/api/v1/swagger/paths/erm_eholdings_resources.yaml b/api/v1/swagger/paths/erm_eholdings_resources.yaml >index a824ed6491d..254bc86293c 100644 >--- a/api/v1/swagger/paths/erm_eholdings_resources.yaml >+++ b/api/v1/swagger/paths/erm_eholdings_resources.yaml >@@ -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 >diff --git a/api/v1/swagger/paths/erm_eholdings_titles.yaml b/api/v1/swagger/paths/erm_eholdings_titles.yaml >index 152fb7f8cea..652aa16b876 100644 >--- a/api/v1/swagger/paths/erm_eholdings_titles.yaml >+++ b/api/v1/swagger/paths/erm_eholdings_titles.yaml >@@ -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 >diff --git a/api/v1/swagger/paths/erm_eholdings_titles_resources.yaml b/api/v1/swagger/paths/erm_eholdings_titles_resources.yaml >index d5ce1e62d09..736f25f784d 100644 >--- a/api/v1/swagger/paths/erm_eholdings_titles_resources.yaml >+++ b/api/v1/swagger/paths/erm_eholdings_titles_resources.yaml >@@ -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 >diff --git a/api/v1/swagger/paths/erm_licenses.yaml b/api/v1/swagger/paths/erm_licenses.yaml >index 97a67527987..51c075c3bd7 100644 >--- a/api/v1/swagger/paths/erm_licenses.yaml >+++ b/api/v1/swagger/paths/erm_licenses.yaml >@@ -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 >diff --git a/api/v1/swagger/paths/erm_users.yaml b/api/v1/swagger/paths/erm_users.yaml >index 8d9bb050231..e9725c4fcac 100644 >--- a/api/v1/swagger/paths/erm_users.yaml >+++ b/api/v1/swagger/paths/erm_users.yaml >@@ -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" >diff --git a/api/v1/swagger/paths/patrons_account.yaml b/api/v1/swagger/paths/patrons_account.yaml >index d67cfb55bb3..df1422764a5 100644 >--- a/api/v1/swagger/paths/patrons_account.yaml >+++ b/api/v1/swagger/paths/patrons_account.yaml >@@ -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 >diff --git a/api/v1/swagger/paths/search_filters.yaml b/api/v1/swagger/paths/search_filters.yaml >index 03de8188d61..6589b1e6c19 100644 >--- a/api/v1/swagger/paths/search_filters.yaml >+++ b/api/v1/swagger/paths/search_filters.yaml >@@ -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" >diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml >index 3faa4805dd1..e84a1c30916 100644 >--- a/api/v1/swagger/swagger.yaml >+++ b/api/v1/swagger/swagger.yaml >@@ -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 >-- >2.39.2
<b>You cannot view the attachment while viewing its details because your browser does not support IFRAMEs. <a href="attachment.cgi?id=154087">View the attachment on a separate page</a>.</b>
View Attachment As Diff
View Attachment As Raw
Actions:
View
|
Diff
|
Splinter Review
Attachments on
bug 34387
:
153891
|
153894
|
153895
|
154065
|
154066
|
154067
| 154087 |
154088
|
154089
|
154090
|
154091
|
154092
|
154419
|
154420