From 75cff54c53ca19617d700bcd1a9c5fefa3bf1839 Mon Sep 17 00:00:00 2001 From: Tomas Cohen Arazi 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'. Signed-off-by: Martin Renvoize Signed-off-by: Tomas Cohen Arazi --- 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 e54f47823f..4e543f7a8d 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 faa824d5b0..029b66c207 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 31ea135413..80be3279b3 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 32cb417240..1d2f3db4ce 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 8b8145d5a9..772554fe8b 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 f5753b200f..1374a20471 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 6fcc1f0802..bfb018c21c 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 3ea8f46a63..1b30c6a05b 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 3fe54fe311..6dc6c4ebe6 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 313fd6f05d..2798062416 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 1a282ab1cf..eaf96e9107 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 3e388542ba..1948ad86af 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 48d8b5af62..c2c2a3e099 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