Bugzilla – Attachment 153891 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]
Bug 34387: Improve API docs naming consistency
Bug-34387-Improve-API-docs-naming-consistency.patch (text/plain), 17.01 KB, created by
Tomás Cohen Arazi (tcohen)
on 2023-07-25 19:09:00 UTC
(
hide
)
Description:
Bug 34387: Improve API docs naming consistency
Filename:
MIME Type:
Creator:
Tomás Cohen Arazi (tcohen)
Created:
2023-07-25 19:09:00 UTC
Size:
17.01 KB
patch
obsolete
>From c7a7c870f720bb7ece7884cebb15e48dc2153f72 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] 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'. >--- > api/v1/swagger/paths/erm_agreements.yaml | 10 ++-- > api/v1/swagger/paths/erm_config.yaml | 2 +- > 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 | 60 +++++++++++++++---- > 13 files changed, 79 insertions(+), 45 deletions(-) > >diff --git a/api/v1/swagger/paths/erm_agreements.yaml b/api/v1/swagger/paths/erm_agreements.yaml >index e54f47823fb..4e543f7a8dc 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 >@@ -108,7 +108,7 @@ > x-mojo-to: ERM::Agreements#add > operationId: addErmAgreements > tags: >- - agreement >+ - erm_agreements > summary: Add agreement > consumes: > - application/json >@@ -169,7 +169,7 @@ > x-mojo-to: ERM::Agreements#get > operationId: getErmAgreements > tags: >- - agreement >+ - erm_agreements > summary: Get agreement > produces: > - application/json >@@ -231,7 +231,7 @@ > x-mojo-to: ERM::Agreements#update > operationId: updateErmAgreements > tags: >- - agreement >+ - erm_agreements > summary: Update agreement > consumes: > - application/json >@@ -302,7 +302,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_config.yaml b/api/v1/swagger/paths/erm_config.yaml >index faa824d5b02..029b66c2076 100644 >--- a/api/v1/swagger/paths/erm_config.yaml >+++ b/api/v1/swagger/paths/erm_config.yaml >@@ -6,7 +6,7 @@ > description: This resource returns a list of options needed for the ERM Vue app. EXPERIMENTAL - DO NOT RELY on this, it is subject to change! > summary: get the ERM config > tags: >- - ERM >+ - erm_config > produces: > - application/json > responses: >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 32cb417240c..1d2f3db4ced 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 >@@ -105,7 +105,7 @@ > x-mojo-to: ERM::EHoldings::Packages#add > operationId: addErmEHoldingsPackages > tags: >- - eHoldings package >+ - erm_eholdings_packages > summary: Add package > consumes: > - application/json >@@ -167,7 +167,7 @@ > x-mojo-to: ERM::EHoldings::Packages#get > operationId: getErmEHoldingsPackages > tags: >- - package >+ - erm_eholdings_packages > summary: Get eHoldings package > produces: > - application/json >@@ -226,7 +226,7 @@ > x-mojo-to: ERM::EHoldings::Packages#update > operationId: updateErmEHoldingsPackages > tags: >- - package >+ - erm_eholdings_packages > summary: Update eHoldings package > consumes: > - application/json >@@ -295,7 +295,7 @@ > x-mojo-to: ERM::EHoldings::Packages#delete > operationId: deleteErmEHoldingsPackages > tags: >- - package >+ - erm_eholdings_packages > summary: Delete eHoldings package > produces: > - application/json >@@ -346,7 +346,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 8b8145d5a94..772554fe8b1 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 f5753b200f6..1374a20471a 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 >@@ -83,7 +83,7 @@ > x-mojo-to: ERM::EHoldings::Resources#get > operationId: getErmEHoldingsResources > tags: >- - eholdings >+ - erm_eholdings_resources > summary: Get resources > produces: > - application/json >@@ -141,7 +141,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 6fcc1f08028..bfb018c21cc 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 >@@ -192,7 +192,7 @@ > x-mojo-to: ERM::EHoldings::Titles#add > operationId: addErmEHoldingsTitles > tags: >- - eholdings >+ - erm_eholdings_titles > summary: Add eholding > consumes: > - application/json >@@ -254,7 +254,7 @@ > x-mojo-to: ERM::EHoldings::Titles#get > operationId: getErmEHoldingsTitles > tags: >- - eholdings >+ - erm_eholdings_titles > summary: Get titles > produces: > - application/json >@@ -311,7 +311,7 @@ > x-mojo-to: ERM::EHoldings::Titles#update > operationId: updateErmEHoldingsTitles > tags: >- - eholdings >+ - erm_eholdings_titles > summary: Update titles > consumes: > - application/json >@@ -380,7 +380,7 @@ > x-mojo-to: ERM::EHoldings::Titles#delete > operationId: deleteErmEHoldingsTitles > tags: >- - eholdings >+ - erm_eholdings_titles > summary: Delete eHolding title > produces: > - application/json >@@ -432,7 +432,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 3ea8f46a63e..1b30c6a05ba 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 3fe54fe311b..6dc6c4ebe69 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 >@@ -91,7 +91,7 @@ > x-mojo-to: ERM::Licenses#add > operationId: addERMLicenses > tags: >- - license >+ - erm_licences > summary: Add license > consumes: > - application/json >@@ -152,7 +152,7 @@ > x-mojo-to: ERM::Licenses#get > operationId: getERMlicense > tags: >- - license >+ - erm_licences > summary: get license > produces: > - application/json >@@ -206,7 +206,7 @@ > x-mojo-to: ERM::Licenses#update > operationId: updateERMlicenses > tags: >- - license >+ - erm_licences > summary: update license > consumes: > - application/json >@@ -274,7 +274,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 313fd6f05df..27980624161 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 1a282ab1cfe..eaf96e91071 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 >@@ -136,7 +135,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 3e388542ba6..1948ad86af2 100644 >--- a/api/v1/swagger/paths/search_filters.yaml >+++ b/api/v1/swagger/paths/search_filters.yaml >@@ -164,7 +164,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 48d8b5af628..c2c2a3e099d 100644 >--- a/api/v1/swagger/swagger.yaml >+++ b/api/v1/swagger/swagger.yaml >@@ -779,15 +779,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 >@@ -812,12 +815,39 @@ 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 configuration\n" >+ name: erm_config >+ x-displayName: ERM configuration >+ - 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 >@@ -851,6 +881,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 >@@ -860,18 +893,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=153891">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