Koha-clms/api/v1/swagger/paths
Tomas Cohen Arazi 75cff54c53
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>
2023-08-15 11:25:35 +03:00
..
acquisitions_baskets.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
acquisitions_funds.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
acquisitions_orders.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
acquisitions_vendor_issues.yaml Bug 33105: (QA follow-up) REST API 2023-07-20 10:59:29 -03:00
acquisitions_vendors.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
advancededitormacros.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
article_requests.yaml Bug 30194: (follow-up) Simply OpenAPI Specification 2022-03-29 16:44:31 +02:00
auth.yaml Bug 32739: Allow other patron identifier on pwd validation 2023-07-25 16:25:37 -03:00
authorised_value_categories.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
authorised_values.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
authorities.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
biblios.yaml Bug 34211: Add +strings for GET /api/v1/biblios/:biblio_id/items 2023-07-13 15:19:34 -03:00
biblios_item_groups.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
cash_registers.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
checkouts.yaml Bug 30979: Fix xt/api.t 2023-07-14 16:52:02 -03:00
circulation-rules.yaml Bug 30194: (follow-up) Simply OpenAPI Specification 2022-03-29 16:44:31 +02:00
cities.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
clubs.yaml Bug 30194: (follow-up) Simply OpenAPI Specification 2022-03-29 16:44:31 +02:00
config_smtp_servers.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
erm_agreements.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
erm_config.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
erm_documents.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
erm_eholdings_packages.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
erm_eholdings_packages_resources.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
erm_eholdings_resources.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
erm_eholdings_titles.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
erm_eholdings_titles_resources.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
erm_licenses.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
erm_users.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
holds.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
ill_backends.yaml Bug 22440: Move backend statuses api endpoint 2023-05-05 09:13:43 -03:00
ill_requests.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
import_batch_profiles.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
import_batches.yaml Bug 30855: Rename /import => /import_batches 2022-06-02 13:42:28 -03:00
items.yaml Bug 32711: Add biblio details to modal 2023-07-24 13:58:20 -03:00
jobs.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
libraries.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
oauth.yaml Bug 32354: Accept session_state param given by OAuth IdP 2022-12-07 12:58:32 -03:00
patrons.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
patrons_account.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
patrons_extended_attributes.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
patrons_holds.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
patrons_password.yaml Bug 29926: (QA follow-up) Date format missing in spec 2022-05-06 10:33:10 -10:00
public_oauth.yaml Bug 32354: Accept session_state param given by OAuth IdP 2022-12-07 12:58:32 -03:00
public_patrons.yaml Bug 30979: (QA follow-up) Add missing docs on error codes 2023-07-14 12:14:46 -03:00
quotes.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
return_claims.yaml Bug 30194: (follow-up) Simply OpenAPI Specification 2022-03-29 16:44:31 +02:00
rotas.yaml Bug 30194: (follow-up) Simply OpenAPI Specification 2022-03-29 16:44:31 +02:00
search_filters.yaml Bug 34387: Improve API docs naming consistency 2023-08-15 11:25:35 +03:00
suggestions.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
tickets.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00
transfer_limits.yaml Bug 33971: Remove x-koha-query header support 2023-07-03 10:35:06 -03:00