From 4830b65fcce6b954e973d67307e8edbac7a422af Mon Sep 17 00:00:00 2001 From: Jonathan Druart Date: Thu, 24 Mar 2022 08:54:59 +0100 Subject: [PATCH] Bug 30194: Auto generate swagger.yaml It was not sorted correct and had inconsistencies. use YAML; use File::Slurp qw( write_file ); my $hash = YAML::LoadFile('api/v1/swagger/swagger.yaml'); YAML::Bless($hash)->keys([qw(swagger basePath definitions paths info tags)]); my $info = $hash->{info}; YAML::Bless($info)->keys([qw(title version license contact description)]); my $yaml= YAML::Dump($hash); $yaml =~ s|'|"|xmsg; write_file('api/v1/swagger/swagger.yaml', $yaml); --- api/v1/swagger/swagger.yaml | 359 +++++++++++++++++------------------- 1 file changed, 167 insertions(+), 192 deletions(-) diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml index 09425a8d7dc..bc3acbea1bb 100644 --- a/api/v1/swagger/swagger.yaml +++ b/api/v1/swagger/swagger.yaml @@ -1,5 +1,5 @@ --- -swagger: "2.0" +swagger: 2.0 basePath: /api/v1 definitions: account_line: @@ -65,329 +65,304 @@ definitions: vendor: $ref: definitions/vendor.yaml paths: - /oauth/token: - $ref: paths/oauth.yaml#/~1oauth~1token + /acquisitions/funds: + $ref: paths/acquisitions_funds.yaml#/~1acquisitions~1funds /acquisitions/orders: $ref: paths/acquisitions_orders.yaml#/~1acquisitions~1orders "/acquisitions/orders/{order_id}": - $ref: paths/acquisitions_orders.yaml#/~1acquisitions~1orders~1{order_id} + $ref: "paths/acquisitions_orders.yaml#/~1acquisitions~1orders~1{order_id}" /acquisitions/vendors: $ref: paths/acquisitions_vendors.yaml#/~1acquisitions~1vendors "/acquisitions/vendors/{vendor_id}": - $ref: paths/acquisitions_vendors.yaml#/~1acquisitions~1vendors~1{vendor_id} - /acquisitions/funds: - $ref: paths/acquisitions_funds.yaml#/~1acquisitions~1funds + $ref: "paths/acquisitions_vendors.yaml#/~1acquisitions~1vendors~1{vendor_id}" + /advanced_editor/macros: + $ref: paths/advancededitormacros.yaml#/~1advanced_editor~1macros + /advanced_editor/macros/shared: + $ref: paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared + "/advanced_editor/macros/shared/{advancededitormacro_id}": + $ref: "paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared~1{advancededitormacro_id}" + "/advanced_editor/macros/{advancededitormacro_id}": + $ref: "paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1{advancededitormacro_id}" "/article_requests/{article_request_id}": - $ref: paths/article_requests.yaml#/~1article_requests~1{article_request_id} + $ref: "paths/article_requests.yaml#/~1article_requests~1{article_request_id}" "/biblios/{biblio_id}": - $ref: paths/biblios.yaml#/~1biblios~1{biblio_id} + $ref: "paths/biblios.yaml#/~1biblios~1{biblio_id}" "/biblios/{biblio_id}/checkouts": - $ref: paths/biblios.yaml#/~1biblios~1{biblio_id}~1checkouts + $ref: "paths/biblios.yaml#/~1biblios~1{biblio_id}~1checkouts" "/biblios/{biblio_id}/items": - $ref: paths/biblios.yaml#/~1biblios~1{biblio_id}~1items + $ref: "paths/biblios.yaml#/~1biblios~1{biblio_id}~1items" "/biblios/{biblio_id}/pickup_locations": - $ref: paths/biblios.yaml#/~1biblios~1{biblio_id}~1pickup_locations + $ref: "paths/biblios.yaml#/~1biblios~1{biblio_id}~1pickup_locations" "/cash_registers/{cash_register_id}/cashups": - $ref: paths/cash_registers.yaml#/~1cash_registers~1{cash_register_id}~1cashups + $ref: "paths/cash_registers.yaml#/~1cash_registers~1{cash_register_id}~1cashups" "/cashups/{cashup_id}": - $ref: paths/cash_registers.yaml#/~1cashups~1{cashup_id} + $ref: "paths/cash_registers.yaml#/~1cashups~1{cashup_id}" /checkouts: $ref: paths/checkouts.yaml#/~1checkouts "/checkouts/{checkout_id}": - $ref: paths/checkouts.yaml#/~1checkouts~1{checkout_id} + $ref: "paths/checkouts.yaml#/~1checkouts~1{checkout_id}" + "/checkouts/{checkout_id}/allows_renewal": + $ref: "paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1allows_renewal" "/checkouts/{checkout_id}/renewal": - $ref: paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1renewal + $ref: "paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1renewal" /circulation-rules/kinds: $ref: paths/circulation-rules.yaml#/~1circulation-rules~1kinds /cities: $ref: paths/cities.yaml#/~1cities "/cities/{city_id}": - $ref: paths/cities.yaml#/~1cities~1{city_id} + $ref: "paths/cities.yaml#/~1cities~1{city_id}" "/clubs/{club_id}/holds": - $ref: paths/clubs.yaml#/~1clubs~1{club_id}~1holds + $ref: "paths/clubs.yaml#/~1clubs~1{club_id}~1holds" /config/smtp_servers: $ref: paths/config_smtp_servers.yaml#/~1config~1smtp_servers "/config/smtp_servers/{smtp_server_id}": - $ref: paths/config_smtp_servers.yaml#/~1config~1smtp_servers~1{smtp_server_id} + $ref: "paths/config_smtp_servers.yaml#/~1config~1smtp_servers~1{smtp_server_id}" /holds: $ref: paths/holds.yaml#/~1holds "/holds/{hold_id}": - $ref: paths/holds.yaml#/~1holds~1{hold_id} + $ref: "paths/holds.yaml#/~1holds~1{hold_id}" + "/holds/{hold_id}/pickup_location": + $ref: "paths/holds.yaml#/~1holds~1{hold_id}~1pickup_location" + "/holds/{hold_id}/pickup_locations": + $ref: "paths/holds.yaml#/~1holds~1{hold_id}~1pickup_locations" "/holds/{hold_id}/priority": - $ref: paths/holds.yaml#/~1holds~1{hold_id}~1priority + $ref: "paths/holds.yaml#/~1holds~1{hold_id}~1priority" "/holds/{hold_id}/suspension": - $ref: paths/holds.yaml#/~1holds~1{hold_id}~1suspension - "/holds/{hold_id}/pickup_locations": - $ref: paths/holds.yaml#/~1holds~1{hold_id}~1pickup_locations - "/holds/{hold_id}/pickup_location": - $ref: paths/holds.yaml#/~1holds~1{hold_id}~1pickup_location + $ref: "paths/holds.yaml#/~1holds~1{hold_id}~1suspension" + /ill_backends: + $ref: paths/ill_backends.yaml#/~1ill_backends + "/ill_backends/{ill_backend_id}": + $ref: "paths/ill_backends.yaml#/~1ill_backends~1{ill_backend_id}" + /illrequests: + $ref: paths/illrequests.yaml#/~1illrequests + /import_batch_profiles: + $ref: paths/import_batch_profiles.yaml#/~1import_batch_profiles + "/import_batch_profiles/{import_batch_profile_id}": + $ref: "paths/import_batch_profiles.yaml#/~1import_batch_profiles~1{import_batch_profile_id}" /items: $ref: paths/items.yaml#/~1items "/items/{item_id}": - $ref: paths/items.yaml#/~1items~1{item_id} + $ref: "paths/items.yaml#/~1items~1{item_id}" "/items/{item_id}/pickup_locations": - $ref: paths/items.yaml#/~1items~1{item_id}~1pickup_locations + $ref: "paths/items.yaml#/~1items~1{item_id}~1pickup_locations" /libraries: $ref: paths/libraries.yaml#/~1libraries "/libraries/{library_id}": - $ref: paths/libraries.yaml#/~1libraries~1{library_id} - /transfer_limits: - $ref: paths/transfer_limits.yaml#/~1transfer_limits - "/transfer_limits/{limit_id}": - $ref: paths/transfer_limits.yaml#/~1transfer_limits~1{limit_id} - /transfer_limits/batch: - $ref: paths/transfer_limits.yaml#/~1transfer_limits~1batch - "/checkouts/{checkout_id}/allows_renewal": - $ref: paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1allows_renewal - /advanced_editor/macros: - $ref: paths/advancededitormacros.yaml#/~1advanced_editor~1macros - "/advanced_editor/macros/{advancededitormacro_id}": - $ref: paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1{advancededitormacro_id} - /advanced_editor/macros/shared: - $ref: paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared - "/advanced_editor/macros/shared/{advancededitormacro_id}": - $ref: paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared~1{advancededitormacro_id} + $ref: "paths/libraries.yaml#/~1libraries~1{library_id}" + /oauth/token: + $ref: paths/oauth.yaml#/~1oauth~1token /patrons: $ref: paths/patrons.yaml#/~1patrons "/patrons/{patron_id}": - $ref: paths/patrons.yaml#/~1patrons~1{patron_id} + $ref: "paths/patrons.yaml#/~1patrons~1{patron_id}" "/patrons/{patron_id}/account": - $ref: paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account + $ref: "paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account" "/patrons/{patron_id}/account/credits": - $ref: paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account~1credits + $ref: "paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account~1credits" "/patrons/{patron_id}/extended_attributes": - $ref: paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes + $ref: "paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes" "/patrons/{patron_id}/extended_attributes/{extended_attribute_id}": - $ref: paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes~1{extended_attribute_id} + $ref: "paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes~1{extended_attribute_id}" "/patrons/{patron_id}/holds": - $ref: paths/patrons_holds.yaml#/~1patrons~1{patron_id}~1holds + $ref: "paths/patrons_holds.yaml#/~1patrons~1{patron_id}~1holds" "/patrons/{patron_id}/password": - $ref: paths/patrons_password.yaml#/~1patrons~1{patron_id}~1password - /ill_backends: - $ref: paths/ill_backends.yaml#/~1ill_backends - "/ill_backends/{ill_backend_id}": - $ref: paths/ill_backends.yaml#/~1ill_backends~1{ill_backend_id} - /illrequests: - $ref: paths/illrequests.yaml#/~1illrequests - /import_batch_profiles: - $ref: paths/import_batch_profiles.yaml#/~1import_batch_profiles - "/import_batch_profiles/{import_batch_profile_id}": - $ref: paths/import_batch_profiles.yaml#/~1import_batch_profiles~1{import_batch_profile_id} - "/rotas/{rota_id}/stages/{stage_id}/position": - $ref: paths/rotas.yaml#/~1rotas~1{rota_id}~1stages~1{stage_id}~1position + $ref: "paths/patrons_password.yaml#/~1patrons~1{patron_id}~1password" "/public/biblios/{biblio_id}": - $ref: paths/biblios.yaml#/~1public~1biblios~1{biblio_id} + $ref: "paths/biblios.yaml#/~1public~1biblios~1{biblio_id}" "/public/biblios/{biblio_id}/items": - $ref: paths/biblios.yaml#/~1public~1biblios~1{biblio_id}~1items + $ref: "paths/biblios.yaml#/~1public~1biblios~1{biblio_id}~1items" /public/libraries: $ref: paths/libraries.yaml#/~1public~1libraries "/public/libraries/{library_id}": - $ref: paths/libraries.yaml#/~1public~1libraries~1{library_id} + $ref: "paths/libraries.yaml#/~1public~1libraries~1{library_id}" "/public/patrons/{patron_id}/article_requests/{article_request_id}": - $ref: paths/article_requests.yaml#/~1public~1patrons~1{patron_id}~1article_requests~1{article_request_id} - "/public/patrons/{patron_id}/password": - $ref: paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1password + $ref: "paths/article_requests.yaml#/~1public~1patrons~1{patron_id}~1article_requests~1{article_request_id}" "/public/patrons/{patron_id}/guarantors/can_see_charges": - $ref: paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_charges + $ref: "paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_charges" "/public/patrons/{patron_id}/guarantors/can_see_checkouts": - $ref: paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_checkouts + $ref: "paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_checkouts" + "/public/patrons/{patron_id}/password": + $ref: "paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1password" /quotes: $ref: paths/quotes.yaml#/~1quotes "/quotes/{quote_id}": - $ref: paths/quotes.yaml#/~1quotes~1{quote_id} + $ref: "paths/quotes.yaml#/~1quotes~1{quote_id}" /return_claims: $ref: paths/return_claims.yaml#/~1return_claims + "/return_claims/{claim_id}": + $ref: "paths/return_claims.yaml#/~1return_claims~1{claim_id}" "/return_claims/{claim_id}/notes": - $ref: paths/return_claims.yaml#/~1return_claims~1{claim_id}~1notes + $ref: "paths/return_claims.yaml#/~1return_claims~1{claim_id}~1notes" "/return_claims/{claim_id}/resolve": - $ref: paths/return_claims.yaml#/~1return_claims~1{claim_id}~1resolve - "/return_claims/{claim_id}": - $ref: paths/return_claims.yaml#/~1return_claims~1{claim_id} + $ref: "paths/return_claims.yaml#/~1return_claims~1{claim_id}~1resolve" + "/rotas/{rota_id}/stages/{stage_id}/position": + $ref: "paths/rotas.yaml#/~1rotas~1{rota_id}~1stages~1{stage_id}~1position" /suggestions: $ref: paths/suggestions.yaml#/~1suggestions "/suggestions/{suggestion_id}": - $ref: paths/suggestions.yaml#/~1suggestions~1{suggestion_id} + $ref: "paths/suggestions.yaml#/~1suggestions~1{suggestion_id}" + /transfer_limits: + $ref: paths/transfer_limits.yaml#/~1transfer_limits + /transfer_limits/batch: + $ref: paths/transfer_limits.yaml#/~1transfer_limits~1batch + "/transfer_limits/{limit_id}": + $ref: "paths/transfer_limits.yaml#/~1transfer_limits~1{limit_id}" info: title: Koha REST API - version: "1" + version: 1 license: - name: GPL v3, + name: "GPL v3," url: http://www.gnu.org/licenses/gpl.txt contact: name: Koha Development Team url: https://koha-community.org/ description: | ## Introduction - + This API is documented in **OpenAPI format**. - + ## Authentication - + The API supports the following authentication mechanisms - + * HTTP Basic authentication * OAuth2 (client credentials grant) * Cookie-based - + Both _Basic authentication_ and the _OAuth2_ flow, need to be enabled by system preferences. - + ## Errors - + The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format: - + ``` { "error": "Current settings prevent the passed due date to be applied", "error_code": "invalid_due_date" } ``` - - Note: Some routes might offer additional attributes in their error responses but that's + + Note: Some routes might offer additional attributes in their error responses but that"s subject to change and thus not documented. - + ## Filtering responses - + The API allows for some advanced response filtering using a JSON based query syntax. The query can be added to the requests: - + * as a query parameter `q=` * in the request body * in a special header `x-koha-query` - + For simple field equality matches we can use `{ "fieldname": "value" }` where the fieldname matches one of the fields as described in the particular endpoints response object. - + We can refine that with more complex matching clauses by nesting a the clause into the object; `{ "fieldname": { "clause": "value" } }`. - + Available matching clauses include ">", "<", ">=", "<=", "-like", and "-not_like". - + We can filter on multiple fields by adding them to the JSON respresentation. Adding at `HASH` - level will result in an 'AND' query, whilst combinding them in an `ARRAY` wilth result in an - 'OR' query: `{ "field1": 'value2', "field2": "value2" }` will filter the response to only those + level will result in an "AND" query, whilst combinding them in an `ARRAY` wilth result in an + "OR" query: `{ "field1": "value2", "field2": "value2" }` will filter the response to only those results with both field1 containing value2 AND field2 containing value2 for example. - + ### Examples - + The following request would return any patron with firstname "Henry" and lastname "Acevedo"; - - `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": "Acevedo", "firstname": "Henry" }'` - + + `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": "Acevedo", "firstname": "Henry" }"` + The following request would return any patron whose lastname begins with "Ace"; - - `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": { "-like": "Ace%" }'` - - The following request would return any patron whilse lastname is 'Acevedo' OR 'Bernardo' - - `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": [ "Acevedo", "Bernardo" ] }'` - + + `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": { "-like": "Ace%" }"` + + The following request would return any patron whilse lastname is "Acevedo" OR "Bernardo" + + `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": [ "Acevedo", "Bernardo" ] }"` + ## Special headers - + ### x-koha-library - + 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. + will default to using your api comsumer"s assigned home library. tags: - - name: "article_requests" + - description: "Manage article requests\n" + name: article_requests x-displayName: Article requests - description: | - Manage article requests - - name: "biblios" + - description: "Manage bibliographic records\n" + name: biblios x-displayName: Biblios - description: | - Manage bibliographic records - - name: "cashups" + - description: "Manage cash register cashups\n" + name: cashups x-displayName: Cashups - description: | - Manage cash register cashups - - name: "checkouts" + - description: "Manage checkouts\n" + name: checkouts x-displayName: Checkouts - description: | - Manage checkouts - - name: "circulation_rules" + - description: "Manage circulation rules\n" + name: circulation_rules x-displayName: Circulation rules - description: | - Manage circulation rules - - name: "cities" + - description: "Manage cities\n" + name: cities x-displayName: Cities - description: | - Manage cities - - name: "clubs" + - description: "Manage patron clubs\n" + name: clubs x-displayName: Clubs - description: | - Manage patron clubs - - name: "funds" + - description: "Manage funds for the acquisitions module\n" + name: funds x-displayName: Funds - description: | - Manage funds for the acquisitions module - - name: "holds" + - description: "Manage holds\n" + name: holds x-displayName: Holds - description: | - Manage holds - - name: "illbackends" + - description: "Manage ILL module backends\n" + name: illbackends x-displayName: ILL backends - description: | - Manage ILL module backends - - name: "illrequests" + - description: "Manage ILL requests\n" + name: illrequests x-displayName: ILL requests - description: | - Manage ILL requests - - name: "items" + - description: "Manage items\n" + name: items x-displayName: Items - description: | - Manage items - - name: "libraries" + - description: "Manage libraries\n" + name: libraries x-displayName: Libraries - description: | - Manage libraries - - name: "macros" + - description: "Manage macros\n" + name: macros x-displayName: Macros - description: | - Manage macros - - name: "orders" + - description: "Manage acquisition orders\n" + name: orders x-displayName: Orders - description: | - Manage acquisition orders - - name: "oauth" - x-displayName: "OAuth" - description: | - Handle OAuth flows - - name: "patrons" + - description: "Handle OAuth flows\n" + name: oauth + x-displayName: OAuth + - description: "Manage patrons\n" + name: patrons x-displayName: Patrons - description: | - Manage patrons - - name: "quotes" + - description: "Manage quotes\n" + name: quotes x-displayName: Quotes - description: | - Manage quotes - - name: "return_claims" + - description: "Manage return claims\n" + name: return_claims x-displayName: Return claims - description: | - Manage return claims - - name: "rotas" + - description: "Manage rotas\n" + name: rotas x-displayName: Rotas - description: | - Manage rotas - - name: "smtp_servers" + - description: "Manage SMTP servers configurations\n" + name: smtp_servers x-displayName: SMTP servers - description: | - Manage SMTP servers configurations - - name: "transfer" + - description: "Manage transfer limits\n" + name: transfer x-displayName: Transfer limits - description: | - Manage transfer limits - - name: "suggestions" - x-displayName: "Purchase suggestions" - description: | - Manage purchase suggestions - - name: "vendors" - x-displayName: "Vendors" - description: | - Manage vendors for the acquisitions module - - name: "batch_import_profiles" + - description: "Manage purchase suggestions\n" + name: suggestions + x-displayName: Purchase suggestions + - 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 - description: | - Manage batch import profiles -- 2.25.1