Browse Source

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 <matthias.meusburger@biblibre.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
20.05.x
Tomas Cohen Arazi 5 years ago
committed by Martin Renvoize
parent
commit
5cd9c904c4
Signed by: martin.renvoize GPG Key ID: 422B469130441A0F
  1. 15
      api/v1/swagger/definitions.json
  2. 99
      api/v1/swagger/definitions/basket.json
  3. 57
      api/v1/swagger/definitions/invoice.json
  4. 328
      api/v1/swagger/definitions/order.json
  5. 3
      api/v1/swagger/parameters.json
  6. 9
      api/v1/swagger/parameters/order.json
  7. 6
      api/v1/swagger/paths.json
  8. 378
      api/v1/swagger/paths/acquisitions_orders.json

15
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"
}

99
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)"
}
}
}

57
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
}

328
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"
},
"fund_id": {
"type": "integer",
"description": "Internal identifier for the fund 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
}

3
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"
},

9
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"
}
}

6
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"
},

378
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"
}
}
}
}
}
Loading…
Cancel
Save