Browse Source

Bug 28463: Add tags definitions in swagger.yaml

This patch starts the work of curating the spec documentation-related
aspects. It doesn't involve any functional change on the API, just
labels (used to render docs) and some descriptions basis is added.

- A top level 'tags' entry is added to swagger.yaml.
- The 'name' attribute is left with double quotes. This is on purpose,
  to differentiate from 'x-displayName' which is the actual text to be
  displayer and should be handled by documentation folks, not us, devs
  :-D
- I add a very limited 'description' attribute there. It is the top
  level description of the section. For example the description for the
  'Biblios' section is 'Manage bibliographic records'. As it expects
  Markdown, anything we want can be added there.
- Some labels have been tweaked in paths, to rollback the decision of
  making the labels in paths more end-user friendly. We don't want them
  to be typed much, and I picked what we use the most: snake_case.
- The order in which things are displayed, is the one we specified on
  the swagger.yaml file. The 'batch import profiles' one is left at the
  bottom on purpose. But this is subject to discussion. As a general
  rule, I put them all in alphabetical order (on the x-displayName label
  I mean).

I submit early before family duties so others can pick where I left in
the morning. So:

TODO:
- I'm not sure what's best for Advanced editor macros. My bet is we
  should define a 'Macros' label, and use a summary on the routes
  themselves to specify this are not just 'macros', but advanced editor
  macros. Look at the return claims paths to understand how I propose to
  use the 'summary' attribtue.
- I understand how we use 'rotas', but someone more familiar with the
  terminology,... please... step in.
- Related to the first item here, we need to add summary to all routes,
  so ReDoc doesn't display the operationId anymore. Again, I put an
  example in Return claims that we can follow.

To test:
1. Have KTD running
2. Open your browser at:
   http://localhost:/8080/api/v1/
3. Save the page as spec.json in some known dir
4. Go to that dir and run:
   $ docker run -it --rm -p 8083:80 \
       -v $(pwd)/spec.json:/usr/share/nginx/html/swagger.json \
       -e SPEC_URL=swagger.json redocly/redoc
5. Open your browser at
   http://localhost:8083
=> SUCCESS: You see the docs
6. Look at the list of 'categories' on the left
=> FAIL: They look a bit weird
7. Apply this patch
8. Ctrl+c on the terminal running docker
9. Reload plack
10. Repeat 2 through 6
=> SUCCESS: Wow, things look better!
11. Sign off :-D

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
21.05.x
Tomas Cohen Arazi 8 months ago
committed by Jonathan Druart
parent
commit
f1dca080d4
  1. 10
      api/v1/swagger/paths/config_smtp_servers.json
  2. 8
      api/v1/swagger/paths/import_batch_profiles.json
  3. 4
      api/v1/swagger/paths/patrons_account.json
  4. 2
      api/v1/swagger/paths/patrons_password.json
  5. 6
      api/v1/swagger/paths/public_patrons.json
  6. 8
      api/v1/swagger/paths/return_claims.json
  7. 81
      api/v1/swagger/swagger.yaml

10
api/v1/swagger/paths/config_smtp_servers.json

@ -4,7 +4,7 @@
"x-mojo-to": "Config::SMTP::Servers#list",
"operationId": "listSMTPServers",
"tags": [
"SMTP servers"
"smtp_servers"
],
"produces": [
"application/json"
@ -71,7 +71,7 @@
"x-mojo-to": "Config::SMTP::Servers#add",
"operationId": "addSMTPServer",
"tags": [
"SMTP servers"
"smtp_servers"
],
"parameters": [
{
@ -137,7 +137,7 @@
"x-mojo-to": "Config::SMTP::Servers#get",
"operationId": "getSMTPServer",
"tags": [
"SMTP servers"
"smtp_servers"
],
"parameters": [
{
@ -189,7 +189,7 @@
"x-mojo-to": "Config::SMTP::Servers#update",
"operationId": "updateSMTPServer",
"tags": [
"SMTP servers"
"smtp_servers"
],
"parameters": [
{
@ -256,7 +256,7 @@
"x-mojo-to": "Config::SMTP::Servers#delete",
"operationId": "deleteSMTPServer",
"tags": [
"SMTP servers"
"smtp_servers"
],
"parameters": [
{

8
api/v1/swagger/paths/import_batch_profiles.json

@ -4,7 +4,7 @@
"x-mojo-to": "ImportBatchProfiles#list",
"operationId": "listImportBatchProfiles",
"tags": [
"ImportBatchProfiles"
"batch_import_profiles"
],
"parameters": [
{
@ -75,7 +75,7 @@
"x-mojo-to": "ImportBatchProfiles#add",
"operationId": "addImportBatchProfiles",
"tags": [
"ImportBatchProfiles"
"batch_import_profiles"
],
"parameters": [
{
@ -193,7 +193,7 @@
"x-mojo-to": "ImportBatchProfiles#edit",
"operationId": "editImportBatchProfiles",
"tags": [
"ImportBatchProfiles"
"batch_import_profiles"
],
"parameters": [
{
@ -311,7 +311,7 @@
"delete": {
"x-mojo-to": "ImportBatchProfiles#delete",
"operationId": "deleteImportBatchProfiles",
"tags": ["ImportBatchProfiles"],
"tags": ["batch_import_profiles"],
"parameters": [{
"$ref": "../parameters.json#/import_batch_profile_id_pp"
}

4
api/v1/swagger/paths/patrons_account.json

@ -4,7 +4,7 @@
"x-mojo-to": "Patrons::Account#get",
"operationId": "getPatronAccount",
"tags": [
"patron"
"patrons"
],
"parameters": [
{
@ -65,7 +65,7 @@
"x-mojo-to": "Patrons::Account#add_credit",
"operationId": "addPatronCredit",
"tags": [
"patron"
"patrons"
],
"parameters": [
{

2
api/v1/swagger/paths/patrons_password.json

@ -4,7 +4,7 @@
"x-mojo-to": "Patrons::Password#set",
"operationId": "setPatronPassword",
"tags": [
"patron"
"patrons"
],
"parameters": [
{

6
api/v1/swagger/paths/public_patrons.json

@ -4,7 +4,7 @@
"x-mojo-to": "Patrons::Password#set_public",
"operationId": "setPatronPasswordPublic",
"tags": [
"patron"
"patrons"
],
"parameters": [
{
@ -93,7 +93,7 @@
"x-mojo-to": "Patrons#guarantors_can_see_charges",
"operationId": "setPatronGuarantorsCanSeeCharges",
"tags": [
"patron"
"patrons"
],
"parameters": [
{
@ -169,7 +169,7 @@
"x-mojo-to": "Patrons#guarantors_can_see_checkouts",
"operationId": "setPatronGuarantorsCanSeeCheckouts",
"tags": [
"patron"
"patrons"
],
"parameters": [
{

8
api/v1/swagger/paths/return_claims.json

@ -5,7 +5,7 @@
"operationId": "claimReturned",
"summary": "Add a return claim",
"tags": [
"Return claims"
"return_claims"
],
"parameters": [
{
@ -103,7 +103,7 @@
"operationId": "updateClaimNotes",
"summary": "Update notes",
"tags": [
"Return claims"
"return_claims"
],
"parameters": [
{
@ -193,7 +193,7 @@
"x-mojo-to": "ReturnClaims#delete_claim",
"operationId": "deletedClaim",
"summary": "Delete claim",
"tags": [ "Return claims" ],
"tags": [ "return_claims" ],
"parameters": [
{
"name": "claim_id",
@ -262,7 +262,7 @@
"x-mojo-to": "ReturnClaims#resolve_claim",
"operationId": "updateClaimResolve",
"summary": "Resolve claim",
"tags": [ "Return claims" ],
"tags": [ "return_claims" ],
"parameters": [
{
"name": "claim_id",

81
api/v1/swagger/swagger.yaml

@ -30,3 +30,84 @@ info:
This optional header should be passed to give your api request a library
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:
- name: "biblios"
x-displayName: Biblios
description: |
Manage bibliographic records
- name: "cashups"
x-displayName: Cashups
description: |
Manage cash register cashups
- name: "checkouts"
x-displayName: Checkouts
description: |
Manage checkouts
- name: "cities"
x-displayName: Cities
description: |
Manage cities
- name: "clubs"
x-displayName: Clubs
description: |
Manage patron clubs
- name: "funds"
x-displayName: Funds
description: |
Manage funds for the acquisitions module
- name: "holds"
x-displayName: Holds
description: |
Manage holds
- name: "illbackends"
x-displayName: ILL backends
description: |
Manage ILL module backends
- name: "illrequests"
x-displayName: ILL requests
description: |
Manage ILL requests
- name: "items"
x-displayName: Items
description: |
Manage items
- name: "library"
x-displayName: Libraries
description: |
Manage libraries
- name: "orders"
x-displayName: Orders
description: |
Manage acquisition orders
- name: "oauth"
x-displayName: "OAuth"
description: |
Handle OAuth flows
- name: "patrons"
x-displayName: Patrons
description: |
Manage patrons
- name: "quotes"
x-displayName: Quotes
description: |
Manage quotes
- name: "return_claims"
x-displayName: Return claims
description: |
Manage return claims
- name: "smtp_servers"
x-displayName: SMTP servers
description: |
Manage SMTP servers configurations
- name: "transfer"
x-displayName: Transfer limits
description: |
Manage transfer limits
- name: "vendors"
x-displayName: "Vendors"
description: |
Manage vendors for the acquisitions module
- name: "batch_import_profiles"
x-displayName: Batch import profiles
description: |
Manage batch import profiles

Loading…
Cancel
Save