From 25b6b8b8450c54547f15d8035f4e18bbd9f60ede 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. --- api/v1/swagger/definitions.json | 3 + api/v1/swagger/definitions/order.json | 334 ++++++++++++++++++++++++++ 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 | 324 +++++++++++++++++++++++++ 6 files changed, 679 insertions(+) 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 340b9a978b..0bca1e9be8 100644 --- a/api/v1/swagger/definitions.json +++ b/api/v1/swagger/definitions.json @@ -11,6 +11,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 0000000000..da654f3bdc --- /dev/null +++ b/api/v1/swagger/definitions/order.json @@ -0,0 +1,334 @@ +{ + "type": "object", + "properties": { + "ordernumber": { + "type": "integer", + "description": "Internally assigned order identifier" + }, + "biblionumber": { + "type": [ + "integer", + "null" + ], + "description": "Identifier for the linked bibliographic record" + }, + "entrydate": { + "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" + }, + "listprice": { + "type": [ + "number", + "null" + ], + "description": "Vendor price for the line item" + }, + "datereceived": { + "type": [ + "string", + "null" + ], + "description": "Date the order was received" + }, + "invoiceid": { + "type": [ + "integer", + "null" + ], + "description": "Id of the order invoice" + }, + "freight": { + "type": [ + "number", + "null" + ], + "description": "Shipping costs (TODO: unused?)" + }, + "unitprice": { + "type": [ + "number", + "null" + ], + "description": "The actual cost entered when receiving this line item" + }, + "unitprice_tax_excluded": { + "type": [ + "number", + "null" + ], + "description": "Unit price excluding tax (on receiving)" + }, + "unitprice_tax_included": { + "type": [ + "number", + "null" + ], + "description": "Unit price including tax (on receiving)" + }, + "quantityreceived": { + "type": "integer", + "description": "Quantity received so far" + }, + "datecancellationprinted": { + "type": [ + "string", + "null" + ], + "description": "Date the line item was deleted" + }, + "cancellationreason": { + "type": [ + "string", + "null" + ], + "description": "Reason of cancellation" + }, + "order_internalnote": { + "type": [ + "string", + "null" + ], + "description": "Notes related to this order line, made for staff" + }, + "order_vendornote": { + "type": [ + "string", + "null" + ], + "description": "Notes related to this order line, made for vendor" + }, + "purchaseordernumber": { + "type": [ + "string", + "null" + ], + "description": "(deprecated)" + }, + "basketno": { + "type": [ + "integer", + "null" + ], + "description": "Basket this order is linked to" + }, + "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_bak": { + "type": [ + "number", + "null" + ], + "description": "Tax rate (%)" + }, + "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_bak": { + "type": [ + "number", + "null" + ], + "description": "Tax value" + }, + "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": { + "type": [ + "number", + "null" + ], + "description": "Discount" + }, + "budget_id": { + "type": "integer", + "description": "The ID for the budget this order goes against" + }, + "budgetdate": { + "type": [ + "string", + "null" + ], + "description": "Unused" + }, + "sort1": { + "type": [ + "string", + "null" + ], + "description": "Statistical field" + }, + "sort2": { + "type": [ + "string", + "null" + ], + "description": "Statistical field (2)" + }, + "sort1_authcat": { + "type": [ + "string", + "null" + ], + "description": "Statistical category for this order" + }, + "sort2_authcat": { + "type": [ + "string", + "null" + ], + "description": "Statistical category for this order (2)" + }, + "uncertainprice": { + "type": "boolean", + "description": "If this price was uncertain" + }, + "claims_count": { + "type": "integer", + "description": "Generated claim letters count" + }, + "claimed_date": { + "type": [ + "string", + "null" + ], + "description": "Last date a claim letter was generated" + }, + "subscriptionid": { + "type": [ + "integer", + "null" + ], + "description": "Subscription ID linking the order to a subscription" + }, + "parent_ordernumber": { + "type": [ + "integer", + "null" + ], + "description": "ordernumber of parent order line if exists" + }, + "orderstatus": { + "type": "string", + "enum": [ + "new", + "ordered", + "partial", + "complete", + "cancelled" + ], + "description": "The current status" + }, + "line_item_id": { + "type": [ + "string", + "null" + ], + "description": "Supplier's article id for Edifact orderline" + }, + "suppliers_reference_number": { + "type": [ + "string", + "null" + ], + "description": "Suppliers unique edifact quote reference number" + }, + "suppliers_reference_qualifier": { + "type": [ + "string", + "null" + ], + "description": "Type of reference number usually 'QLI'" + }, + "suppliers_report": { + "type": [ + "string", + "null" + ], + "description": "Reports received from supplier" + } + } +} diff --git a/api/v1/swagger/parameters.json b/api/v1/swagger/parameters.json index b8835d22d1..222b804204 100644 --- a/api/v1/swagger/parameters.json +++ b/api/v1/swagger/parameters.json @@ -11,6 +11,9 @@ "holdIdPathParam": { "$ref": "parameters/hold.json#/holdIdPathParam" }, + "ordernumberPathParam": { + "$ref": "parameters/order.json#/ordernumberPathParam" + }, "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..793995ccb7 --- /dev/null +++ b/api/v1/swagger/parameters/order.json @@ -0,0 +1,9 @@ +{ + "ordernumberPathParam": { + "name": "ordernumber", + "in": "path", + "description": "Order id", + "required": true, + "type": "integer" + } +} diff --git a/api/v1/swagger/paths.json b/api/v1/swagger/paths.json index 9c3a6d2efd..522a961a9f 100644 --- a/api/v1/swagger/paths.json +++ b/api/v1/swagger/paths.json @@ -1,4 +1,10 @@ { + "/acquisitions/orders": { + "$ref": "paths/acquisitions_orders.json#/~1acquisitions~1orders" + }, + "/acquisitions/orders/{ordernumber}": { + "$ref": "paths/acquisitions_orders.json#/~1acquisitions~1orders~1{ordernumber}" + }, "/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..cc57ec7228 --- /dev/null +++ b/api/v1/swagger/paths/acquisitions_orders.json @@ -0,0 +1,324 @@ +{ + "/acquisitions/orders": { + "get": { + "x-mojo-to": "Acquisitions::Orders#list_orders", + "operationId": "listOrders", + "tags": ["acquisitions","orders"], + "produces": [ + "application/json" + ], + "parameters": [{ + "name": "biblionumber", + "in": "query", + "description": "Identifier for a linked bibliographic record", + "required": false, + "type": "integer" + }, { + "name": "basketno", + "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": "orderstatus", + "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": "Vendor 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_order", + "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" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Vendor 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" + } + } + } + }, + "/acquisitions/orders/{ordernumber}": { + "get": { + "x-mojo-to": "Acquisitions::Orders#get_order", + "operationId": "getOrder", + "tags": ["acquisitions","orders"], + "parameters": [{ + "$ref": "../parameters.json#/ordernumberPathParam" + }], + "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_order", + "operationId": "updateOrder", + "tags": ["acquisitions","orders"], + "parameters": [{ + "$ref": "../parameters.json#/ordernumberPathParam" + }, { + "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": "Vendor 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_order", + "operationId": "deleteOrder", + "tags": ["acquisitions","orders"], + "parameters": [{ + "$ref": "../parameters.json#/ordernumberPathParam" + }], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "Vendor deleted", + "schema": { + "type": "string" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Vendor 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.14.1