From 593f9892959d472115033d48edabe88821ad7b43 Mon Sep 17 00:00:00 2001 From: Tomas Cohen Arazi Date: Wed, 4 Oct 2017 15:43:03 -0300 Subject: [PATCH] Bug 18731: OpenAPI definitions This patch introduces the OpenAPI definitions required for the orders endpoint. It matches the voted RFC. Sponsored-by: Camden County Signed-off-by: Matthias Meusburger --- api/v1/swagger/definitions.json | 15 +- api/v1/swagger/definitions/basket.json | 99 +++++ api/v1/swagger/definitions/invoice.json | 57 +++ api/v1/swagger/definitions/order.json | 328 +++++++++++++++ api/v1/swagger/parameters.json | 3 + api/v1/swagger/parameters/order.json | 9 + api/v1/swagger/paths.json | 6 + api/v1/swagger/paths/acquisitions_orders.json | 378 ++++++++++++++++++ 8 files changed, 892 insertions(+), 3 deletions(-) create mode 100644 api/v1/swagger/definitions/basket.json create mode 100644 api/v1/swagger/definitions/invoice.json create mode 100644 api/v1/swagger/definitions/order.json create mode 100644 api/v1/swagger/parameters/order.json create mode 100644 api/v1/swagger/paths/acquisitions_orders.json diff --git a/api/v1/swagger/definitions.json b/api/v1/swagger/definitions.json index 90374145a7..40e10c9f94 100644 --- a/api/v1/swagger/definitions.json +++ b/api/v1/swagger/definitions.json @@ -2,15 +2,24 @@ "account_line": { "$ref": "definitions/account_line.json" }, + "basket": { + "$ref": "definitions/basket.json" + }, "city": { "$ref": "definitions/city.json" }, "error": { "$ref": "definitions/error.json" }, + "fund": { + "$ref": "definitions/fund.json" + }, "hold": { "$ref": "definitions/hold.json" }, + "invoice": { + "$ref": "definitions/invoice.json" + }, "checkouts": { "$ref": "definitions/checkouts.json" }, @@ -26,6 +35,9 @@ "item": { "$ref": "definitions/item.json" }, + "order": { + "$ref": "definitions/order.json" + }, "patron": { "$ref": "definitions/patron.json" }, @@ -41,9 +53,6 @@ "vendor": { "$ref": "definitions/vendor.json" }, - "fund": { - "$ref": "definitions/fund.json" - }, "return_claim": { "$ref": "definitions/return_claim.json" } diff --git a/api/v1/swagger/definitions/basket.json b/api/v1/swagger/definitions/basket.json new file mode 100644 index 0000000000..e5b3b91931 --- /dev/null +++ b/api/v1/swagger/definitions/basket.json @@ -0,0 +1,99 @@ +{ + "type": "object", + "properties": { + "basket_id": { + "type": "integer", + "description": "Internal identifier for the basket" + }, + "name": { + "type": "string", + "description": "Basket name" + }, + "internal_note": { + "type": [ + "string", + "null" + ], + "description": "Internal note" + }, + "vendor_note": { + "type": [ + "string", + "null" + ], + "description": "Vendor note" + }, + "contract_id": { + "type": "integer", + "description": "Internal identifier of the linked contract" + }, + "creation_date": { + "type": [ + "string", + "null" + ], + "format": "date", + "description": "The date the basket was created" + }, + "close_date": { + "type": [ + "string", + "null" + ], + "format": "date", + "description": "The date the basket was closed" + }, + "vendor_id": { + "type": "integer", + "description": "Internal identifier for the vendor" + }, + "authorised_by": { + "type": [ + "integer", + "null" + ], + "description": "Internal patron identifier of the basket creator" + }, + "basket_group_id": { + "type": [ + "integer", + "null" + ], + "description": "links this basket to its group (aqbasketgroups.id)" + }, + "delivery_library": { + "type": [ + "string", + "null" + ], + "description": "basket delivery place" + }, + "billing_library": { + "type": [ + "string", + "null" + ], + "description": "basket billing place" + }, + "library_id": { + "type": [ + "integer", + "null" + ], + "description": "Library the basket belongs to" + }, + "standing": { + "type": "boolean", + "description": "If the orders in this basket are standing" + }, + "create_items": { + "type": "string", + "enum": [ + "ordering", + "receiving", + "cataloguing" + ], + "description": "When items should be created for orders in this basket (Options: 'ordering', 'receiving', 'cataloguing'. Null means system wide config)" + } + } +} diff --git a/api/v1/swagger/definitions/invoice.json b/api/v1/swagger/definitions/invoice.json new file mode 100644 index 0000000000..d86106944e --- /dev/null +++ b/api/v1/swagger/definitions/invoice.json @@ -0,0 +1,57 @@ +{ + "type": "object", + "properties": { + "invoice_id": { + "type": "integer", + "description": "Internal identifier for the incoide. Generated on POST" + }, + "invoice_number": { + "type": "string", + "description": "Invoice number assigned by the vendor" + }, + "vendor_id": { + "type": "integer", + "description": "Internal identifier for the vendor" + }, + "shipping_date": { + "type": [ + "string", + "null" + ], + "format": "date", + "description": "Date of shipping" + }, + "invoice_date": { + "type": [ + "string", + "null" + ], + "format": "date", + "description": "Date of billing" + }, + "closed": { + "type": "boolean", + "description": "If the invoice is closed" + }, + "close_date": { + "type": "string", + "format": "date", + "description": "Invoice close date (only when the invoice is closed)" + }, + "shipping_cost": { + "type": [ + "integer", + "null" + ], + "description": "Shipping cost" + }, + "shipping_cost_budget_id": { + "type": [ + "integer", + "null" + ], + "description": "Shipping cost linking to budget" + } + }, + "additionalProperties": false +} diff --git a/api/v1/swagger/definitions/order.json b/api/v1/swagger/definitions/order.json new file mode 100644 index 0000000000..b5c8b6074a --- /dev/null +++ b/api/v1/swagger/definitions/order.json @@ -0,0 +1,328 @@ +{ + "type": "object", + "properties": { + "order_id": { + "type": "integer", + "description": "Internally assigned order identifier" + }, + "biblio_id": { + "type": [ + "integer", + "null" + ], + "description": "Identifier for the linked bibliographic record" + }, + "created_by": { + "type": "integer", + "description": "Interal patron identifier of the order line creator" + }, + "entry_date": { + "type": [ + "string", + "null" + ], + "format": "date", + "description": "Date the bib was added to the basket" + }, + "quantity": { + "type": [ + "integer", + "null" + ], + "description": "Ordered quantity" + }, + "currency": { + "type": [ + "string", + "null" + ], + "description": "Currency used for the purchase" + }, + "list_price": { + "type": [ + "number", + "null" + ], + "description": "Vendor price for the line item" + }, + "replacement_price": { + "type": [ + "number", + "null" + ], + "description": "Replacement cost for this item" + }, + "date_received": { + "type": [ + "string", + "null" + ], + "format": "date", + "description": "Date the order was received" + }, + "invoice_id": { + "type": [ + "integer", + "null" + ], + "description": "Id of the order invoice" + }, + "shipping_cost": { + "type": [ + "number", + "null" + ], + "description": "Shipping cost" + }, + "unit_price": { + "type": [ + "number", + "null" + ], + "description": "The actual cost entered when receiving this line item" + }, + "unit_price_tax_excluded": { + "type": [ + "number", + "null" + ], + "description": "Unit price excluding tax (on receiving)" + }, + "unit_price_tax_included": { + "type": [ + "number", + "null" + ], + "description": "Unit price including tax (on receiving)" + }, + "quantity_received": { + "type": "integer", + "description": "Quantity received so far" + }, + "cancellation_date": { + "type": [ + "string", + "null" + ], + "format": "date", + "description": "Date the line item was deleted" + }, + "cancellation_reason": { + "type": [ + "string", + "null" + ], + "description": "Reason of cancellation" + }, + "internal_note": { + "type": [ + "string", + "null" + ], + "description": "Notes related to this order line, made for staff" + }, + "vendor_note": { + "type": [ + "string", + "null" + ], + "description": "Notes related to this order line, made for vendor" + }, + "basket_id": { + "type": [ + "integer", + "null" + ], + "description": "Basket this order is linked to" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "Date and time this order line was last modified" + }, + "rrp": { + "type": [ + "number", + "null" + ], + "description": "Retail cost for this item" + }, + "rrp_tax_excluded": { + "type": [ + "number", + "null" + ], + "description": "Replacement cost for this item (tax excluded)" + }, + "rrp_tax_included": { + "type": [ + "number", + "null" + ], + "description": "Replacement cost for this item (tax included)" + }, + "ecost": { + "type": [ + "number", + "null" + ], + "description": "Effective cost" + }, + "ecost_tax_excluded": { + "type": [ + "number", + "null" + ], + "description": "Effective cost (tax excluded)" + }, + "ecost_tax_included": { + "type": [ + "number", + "null" + ], + "description": "Effective cost (tax included)" + }, + "tax_rate_on_ordering": { + "type": [ + "number", + "null" + ], + "description": "Tax rate on ordering (%)" + }, + "tax_rate_on_receiving": { + "type": [ + "number", + "null" + ], + "description": "Tax rate on receiving (%)" + }, + "tax_value_on_ordering": { + "type": [ + "number", + "null" + ], + "description": "Tax value on ordering" + }, + "tax_value_on_receiving": { + "type": [ + "number", + "null" + ], + "description": "Tax value on receiving" + }, + "discount_rate": { + "type": [ + "number", + "null" + ], + "description": "Discount rate" + }, + "budget_id": { + "type": "integer", + "description": "The ID for the budget this order goes against" + }, + "statistics_1": { + "type": [ + "string", + "null" + ], + "description": "Statistical field" + }, + "statistics_2": { + "type": [ + "string", + "null" + ], + "description": "Statistical field (2)" + }, + "statistics_1_authcat": { + "type": [ + "string", + "null" + ], + "description": "Statistical category for this order" + }, + "statistics_2_authcat": { + "type": [ + "string", + "null" + ], + "description": "Statistical category for this order (2)" + }, + "uncertain_price": { + "type": "boolean", + "description": "If this price was uncertain" + }, + "claims_count": { + "type": "integer", + "description": "Generated claim letters count" + }, + "last_claim_date": { + "type": [ + "string", + "null" + ], + "format": "date", + "description": "Last date a claim letter was generated" + }, + "subscription_id": { + "type": [ + "integer", + "null" + ], + "description": "Subscription ID linking the order to a subscription" + }, + "parent_order_id": { + "type": [ + "integer", + "null" + ], + "description": "Order ID of parent order line if exists" + }, + "status": { + "type": "string", + "enum": [ + "new", + "ordered", + "partial", + "complete", + "cancelled" + ], + "description": "The current order status" + }, + "basket": { + "type": [ + "object", + "null" + ] + }, + "biblio": { + "type": [ + "object", + "null" + ] + }, + "fund": { + "type": [ + "object", + "null" + ] + }, + "invoice": { + "type": [ + "object", + "null" + ] + }, + "items": { + "type": "array" + }, + "subscription": { + "type": [ + "object", + "null" + ] + } + }, + "additionalProperties": false +} diff --git a/api/v1/swagger/parameters.json b/api/v1/swagger/parameters.json index 932d251d42..adc455018c 100644 --- a/api/v1/swagger/parameters.json +++ b/api/v1/swagger/parameters.json @@ -23,6 +23,9 @@ "item_id_pp": { "$ref": "parameters/item.json#/item_id_pp" }, + "order_id_pp": { + "$ref": "parameters/order.json#/order_id_pp" + }, "vendoridPathParam": { "$ref": "parameters/vendor.json#/vendoridPathParam" }, diff --git a/api/v1/swagger/parameters/order.json b/api/v1/swagger/parameters/order.json new file mode 100644 index 0000000000..54b4bca3b3 --- /dev/null +++ b/api/v1/swagger/parameters/order.json @@ -0,0 +1,9 @@ +{ + "order_id_pp": { + "name": "order_id", + "in": "path", + "description": "Internal order identifier", + "required": true, + "type": "integer" + } +} diff --git a/api/v1/swagger/paths.json b/api/v1/swagger/paths.json index 95278ec23a..ecf357abb8 100644 --- a/api/v1/swagger/paths.json +++ b/api/v1/swagger/paths.json @@ -2,6 +2,12 @@ "/oauth/token": { "$ref": "paths/oauth.json#/~1oauth~1token" }, + "/acquisitions/orders": { + "$ref": "paths/acquisitions_orders.json#/~1acquisitions~1orders" + }, + "/acquisitions/orders/{order_id}": { + "$ref": "paths/acquisitions_orders.json#/~1acquisitions~1orders~1{order_id}" + }, "/acquisitions/vendors": { "$ref": "paths/acquisitions_vendors.json#/~1acquisitions~1vendors" }, diff --git a/api/v1/swagger/paths/acquisitions_orders.json b/api/v1/swagger/paths/acquisitions_orders.json new file mode 100644 index 0000000000..fc614dd49b --- /dev/null +++ b/api/v1/swagger/paths/acquisitions_orders.json @@ -0,0 +1,378 @@ +{ + "/acquisitions/orders": { + "get": { + "x-mojo-to": "Acquisitions::Orders#list", + "operationId": "listOrders", + "tags": [ + "acquisitions", + "orders" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "biblio_id", + "in": "query", + "description": "Identifier for a linked bibliographic record", + "required": false, + "type": "integer" + }, + { + "name": "basket_id", + "in": "query", + "description": "Identifier for a linked acquisition basket", + "required": false, + "type": "integer" + }, + { + "name": "budget_id", + "in": "query", + "description": "Identifier for the budget the order goes against", + "required": false, + "type": "integer" + }, + { + "name": "status", + "in": "query", + "description": "Current status for the order. Can be 'new', 'ordered', 'partial', 'complete' or 'cancelled'", + "required": false, + "type": "string" + }, + { + "$ref": "../parameters.json#/match" + }, + { + "$ref": "../parameters.json#/order_by" + }, + { + "$ref": "../parameters.json#/page" + }, + { + "$ref": "../parameters.json#/per_page" + } + ], + "responses": { + "200": { + "description": "A list of orders", + "schema": { + "type": "array", + "items": { + "$ref": "../definitions.json#/order" + } + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Order not found", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "503": { + "description": "Under maintenance", + "schema": { + "$ref": "../definitions.json#/error" + } + } + }, + "x-koha-authorization": { + "permissions": { + "acquisition": [ "order_manage", "order_manage_all" ] + } + }, + "x-koha-embed": [ + "basket", + "fund", + "invoice", + "subscription", + "items", + "biblio" + ] + }, + "post": { + "x-mojo-to": "Acquisitions::Orders#add", + "operationId": "addOrder", + "tags": [ + "acquisitions", + "orders" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "description": "A JSON object representing an order", + "required": true, + "schema": { + "$ref": "../definitions.json#/order" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "Order added", + "schema": { + "$ref": "../definitions.json#/order" + } + }, + "400": { + "description": "Bad request", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "409": { + "description": "Conflict in creating the resource", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "503": { + "description": "Under maintenance", + "schema": { + "$ref": "../definitions.json#/error" + } + } + }, + "x-koha-authorization": { + "permissions": { + "acquisition": "order_manage" + } + } + } + }, + "/acquisitions/orders/{order_id}": { + "get": { + "x-mojo-to": "Acquisitions::Orders#get", + "operationId": "getOrder", + "tags": [ + "acquisitions", + "orders" + ], + "parameters": [ + { + "$ref": "../parameters.json#/order_id_pp" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "An order", + "schema": { + "$ref": "../definitions.json#/order" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Order not found", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "503": { + "description": "Under maintenance", + "schema": { + "$ref": "../definitions.json#/error" + } + } + }, + "x-koha-authorization": { + "permissions": { + "acquisition": "order_manage" + } + }, + "x-koha-embed": [ + "basket", + "fund", + "invoice", + "subscription", + "items", + "biblio" + ] + }, + "put": { + "x-mojo-to": "Acquisitions::Orders#update", + "operationId": "updateOrder", + "tags": [ + "acquisitions", + "orders" + ], + "parameters": [ + { + "$ref": "../parameters.json#/order_id_pp" + }, + { + "name": "body", + "in": "body", + "description": "A JSON object representing an order", + "required": true, + "schema": { + "$ref": "../definitions.json#/order" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "An order", + "schema": { + "$ref": "../definitions.json#/order" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Order not found", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "503": { + "description": "Under maintenance", + "schema": { + "$ref": "../definitions.json#/error" + } + } + }, + "x-koha-authorization": { + "permissions": { + "acquisition": "order_manage" + } + } + }, + "delete": { + "x-mojo-to": "Acquisitions::Orders#delete", + "operationId": "deleteOrder", + "tags": [ + "acquisitions", + "orders" + ], + "parameters": [ + { + "$ref": "../parameters.json#/order_id_pp" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "204": { + "description": "Order deleted", + "schema": { + "type": "string" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Order not found", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "503": { + "description": "Under maintenance", + "schema": { + "$ref": "../definitions.json#/error" + } + } + }, + "x-koha-authorization": { + "permissions": { + "acquisition": "order_manage" + } + } + } + } +} -- 2.24.1