From f788586d0888253cb548a4267c457ca51f375847 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 adds query parameters definitions for the reserved params: - _match - _order_by - _page - _per_page Signed-off-by: Matthias Meusburger --- api/v1/swagger/definitions.json | 3 + api/v1/swagger/definitions/order.json | 278 ++++++++++++++++++++++ api/v1/swagger/parameters.json | 5 +- api/v1/swagger/parameters/order.json | 9 + api/v1/swagger/paths.json | 6 + api/v1/swagger/paths/acquisitions_orders.json | 324 ++++++++++++++++++++++++++ 6 files changed, 624 insertions(+), 1 deletion(-) 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 6509432..c2e5a5f 100644 --- a/api/v1/swagger/definitions.json +++ b/api/v1/swagger/definitions.json @@ -14,6 +14,9 @@ "holds": { "$ref": "definitions/holds.json" }, + "order": { + "$ref": "definitions/order.json" + }, "patron": { "$ref": "definitions/patron.json" }, diff --git a/api/v1/swagger/definitions/order.json b/api/v1/swagger/definitions/order.json new file mode 100644 index 0000000..cb2e337 --- /dev/null +++ b/api/v1/swagger/definitions/order.json @@ -0,0 +1,278 @@ +{ + "type": "object", + "properties": { + "order_id": { + "type": "integer", + "description": "Internally assigned order identifier" + }, + "biblio_id": { + "type": [ + "integer", + "null" + ], + "description": "Identifier for the linked bibliographic record" + }, + "entry_date": { + "type": [ + "string", + "null" + ], + "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" + }, + "date_received": { + "type": [ + "string", + "null" + ], + "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" + ], + "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. If ommited, a new basket is automatically created" + }, + "timestamp": { + "type": "string", + "description": "Date and time this order line was last modified" + }, + "rrp": { + "type": [ + "number", + "null" + ], + "description": "Replacement 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" + ], + "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" + } + } +} diff --git a/api/v1/swagger/parameters.json b/api/v1/swagger/parameters.json index d951cf7..4fa42cd 100644 --- a/api/v1/swagger/parameters.json +++ b/api/v1/swagger/parameters.json @@ -11,6 +11,9 @@ "holdIdPathParam": { "$ref": "parameters/hold.json#/holdIdPathParam" }, + "order_id_pp": { + "$ref": "parameters/order.json#/order_id_pp" + }, "vendoridPathParam": { "$ref": "parameters/vendor.json#/vendoridPathParam" }, @@ -51,5 +54,5 @@ "required": false, "description": "Page size, for paginated object listing", "type": "integer" - } + } } diff --git a/api/v1/swagger/parameters/order.json b/api/v1/swagger/parameters/order.json new file mode 100644 index 0000000..5a2c930 --- /dev/null +++ b/api/v1/swagger/parameters/order.json @@ -0,0 +1,9 @@ +{ + "order_id_pp": { + "name": "order_id", + "in": "path", + "description": "Internally assigned order ID", + "required": true, + "type": "integer" + } +} diff --git a/api/v1/swagger/paths.json b/api/v1/swagger/paths.json index c8870db..715b665 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 0000000..65e9d75 --- /dev/null +++ b/api/v1/swagger/paths/acquisitions_orders.json @@ -0,0 +1,324 @@ +{ + "/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", + "acquisition": "order_manage_all" + } + } + }, + "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": { + "200": { + "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" + } + }, + "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" + } + } + }, + "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": { + "200": { + "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.7.4