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>

diff --git a/api/v1/swagger/definitions.json b/api/v1/swagger/definitions.json
index 9037414..40e10c9 100644 (file)
--- 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 (file)
index 0000000..e5b3b91
--- /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 (file)
index 0000000..d861069
--- /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 (file)
index 0000000..f3d07d3
--- /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"
+        },
+        "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
+}

diff --git a/api/v1/swagger/parameters.json b/api/v1/swagger/parameters.json
index 932d251..adc4550 100644 (file)
--- 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 (file)
index 0000000..54b4bca
--- /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 95278ec..ecf357a 100644 (file)
--- 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 (file)
index 0000000..fc614dd
--- /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"
+                }
+            }
+        }
+    }
+}