@@ -, +, @@ - 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'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. http://localhost:/8080/api/v1/ $ docker run -it --rm -p 8083:80 \ -v $(pwd)/spec.json:/usr/share/nginx/html/swagger.json \ -e SPEC_URL=swagger.json redocly/redoc http://localhost:8083 --- 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(-) --- a/api/v1/swagger/paths/config_smtp_servers.json +++ a/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": [ { --- a/api/v1/swagger/paths/import_batch_profiles.json +++ a/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" } --- a/api/v1/swagger/paths/patrons_account.json +++ a/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": [ { --- a/api/v1/swagger/paths/patrons_password.json +++ a/api/v1/swagger/paths/patrons_password.json @@ -4,7 +4,7 @@ "x-mojo-to": "Patrons::Password#set", "operationId": "setPatronPassword", "tags": [ - "patron" + "patrons" ], "parameters": [ { --- a/api/v1/swagger/paths/public_patrons.json +++ a/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": [ { --- a/api/v1/swagger/paths/return_claims.json +++ a/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", --- a/api/v1/swagger/swagger.yaml +++ a/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 --