Attachment 73960 Details for Bug 18731 – Bug 18731: OpenAPI definitions

[patch] Bug 18731: OpenAPI definitions

Bug-18731-OpenAPI-definitions.patch (text/plain), 17.81 KB, created by Tomás Cohen Arazi (tcohen) on 2018-04-10 16:18:49 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Tomás Cohen Arazi (tcohen)

Created: 2018-04-10 16:18:49 UTC

Size: 17.81 KB

patch

obsolete

>From 00f12b5be07bb9a26fc2fdfac1f392a9ece1c2df Mon Sep 17 00:00:00 2001
>From: Tomas Cohen Arazi <tomascohen@theke.io>
>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
>---
> 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 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..cb2e337574
>--- /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 d951cf7d99..4fa42cde66 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 0000000000..5a2c930452
>--- /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 f3e843e6c3..adafe1d975 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/{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..65e9d75f6d
>--- /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.17.0

Actions: View | Diff | Splinter Review

Attachments on bug 18731: 69184 | 69185 | 69309 | 69310 | 69544 | 73959 | 73960 | 78435 | 78436 | 84133 | 84134 | 95054 | 95055 | 95056 | 96853 | 96854 | 96855 | 96856 | 96857 | 96858 | 96916 | 96917 | 96918 | 96938 | 96961 | 96962 | 96963 | 96964 | 96965 | 96966 | 97107 | 97108 | 97109 | 97110 | 97111 | 97112 | 97113 | 97331