Attachment 121445 Details for Bug 28463 – Bug 28463: Add tags definitions in swagger.yaml

[patch] Bug 28463: Add tags definitions in swagger.yaml

Bug-28463-Add-tags-definitions-in-swaggeryaml.patch (text/plain), 11.51 KB, created by Tomás Cohen Arazi (tcohen) on 2021-05-27 11:29:44 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Tomás Cohen Arazi (tcohen)

Created: 2021-05-27 11:29:44 UTC

Size: 11.51 KB

patch

obsolete

>From 247bf10dd9cfacd38887a3a094a4f3203e8f8389 Mon Sep 17 00:00:00 2001
>From: Tomas Cohen Arazi <tomascohen@theke.io>
>Date: Wed, 26 May 2021 17:29:42 -0300
>Subject: [PATCH] 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>
>---
> api/v1/swagger/paths/config_smtp_servers.json | 10 +--
> .../swagger/paths/import_batch_profiles.json  |  8 +-
> api/v1/swagger/paths/patrons_account.json     |  4 +-
> api/v1/swagger/paths/patrons_password.json    |  2 +-
> api/v1/swagger/paths/public_patrons.json      |  6 +-
> api/v1/swagger/paths/return_claims.json       |  8 +-
> api/v1/swagger/swagger.yaml                   | 81 +++++++++++++++++++
> 7 files changed, 100 insertions(+), 19 deletions(-)
>
>diff --git a/api/v1/swagger/paths/config_smtp_servers.json b/api/v1/swagger/paths/config_smtp_servers.json
>index 6fad941e74..26009afb4d 100644
>--- a/api/v1/swagger/paths/config_smtp_servers.json
>+++ b/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": [
>         {
>diff --git a/api/v1/swagger/paths/import_batch_profiles.json b/api/v1/swagger/paths/import_batch_profiles.json
>index 14853ab4ba..39436f5fbc 100644
>--- a/api/v1/swagger/paths/import_batch_profiles.json
>+++ b/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"
>         }
>diff --git a/api/v1/swagger/paths/patrons_account.json b/api/v1/swagger/paths/patrons_account.json
>index 9033645d39..8956ad2f6f 100644
>--- a/api/v1/swagger/paths/patrons_account.json
>+++ b/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": [
>         {
>diff --git a/api/v1/swagger/paths/patrons_password.json b/api/v1/swagger/paths/patrons_password.json
>index 2de2e29c92..ae1686179f 100644
>--- a/api/v1/swagger/paths/patrons_password.json
>+++ b/api/v1/swagger/paths/patrons_password.json
>@@ -4,7 +4,7 @@
>       "x-mojo-to": "Patrons::Password#set",
>       "operationId": "setPatronPassword",
>       "tags": [
>-        "patron"
>+        "patrons"
>       ],
>       "parameters": [
>         {
>diff --git a/api/v1/swagger/paths/public_patrons.json b/api/v1/swagger/paths/public_patrons.json
>index 7b424d964f..6d1d26c840 100644
>--- a/api/v1/swagger/paths/public_patrons.json
>+++ b/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": [
>                 {
>diff --git a/api/v1/swagger/paths/return_claims.json b/api/v1/swagger/paths/return_claims.json
>index b2459c189f..2141f9168d 100644
>--- a/api/v1/swagger/paths/return_claims.json
>+++ b/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",
>diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml
>index bb246f8eb3..b89370491d 100644
>--- a/api/v1/swagger/swagger.yaml
>+++ b/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
>-- 
>2.31.1

Actions: View | Diff | Splinter Review

Attachments on bug 28463: 121445 | 121450 | 121451 | 121453 | 121454 | 121455