Bug 20942: OpenAPI spec for /patrons/{patron_id}/account

This patch adds the OpenAPI spec for the following paths:
- /patrons/{patron_id}/account

It also adds object definitions for:
- balance
- account line

Account line is to be used on both /account/lines (when implemented)
and for embeding the outstanding lines in the balance endpoint
(/patrons/{patron_id}/account).

Signed-off-by: Josef Moravec <josef.moravec@gmail.com>

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>

Signed-off-by: Nick Clemens <nick@bywatersolutions.com>

api/v1/swagger/definitions.json

@@ -1,4 +1,7 @@
 {
+  "account_line": {
+    "$ref": "definitions/account_line.json"
+  },
   "city": {
     "$ref": "definitions/city.json"
   },
@@ -14,8 +17,8 @@
   "patron": {
     "$ref": "definitions/patron.json"
   },
-  "error": {
-    "$ref": "definitions/error.json"
+  "patron_balance": {
+    "$ref": "definitions/patron_balance.json"
   },
   "vendor": {
     "$ref": "definitions/vendor.json"

api/v1/swagger/definitions/account_line.json

@@ -0,0 +1,81 @@
+{
+  "type": "object",
+  "properties": {
+    "account_line_id": {
+      "type": "integer",
+      "description": "Internal account line identifier"
+    },
+    "checkout_id": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "description": "Internal identifier for the checkout the account line is related to"
+    },
+    "patron_id": {
+      "type": "integer",
+      "description": "Internal identifier for the patron the account line belongs to"
+    },
+    "item_id": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "description": "Internal identifier for the item the account line is related to"
+    },
+    "date": {
+      "type": "string",
+      "format": "date",
+      "description": "Date the account line was created"
+    },
+    "amount": {
+      "type": "number",
+      "description": "Account line amount"
+    },
+    "description": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Account line description"
+    },
+    "account_type": {
+      "type": "string",
+      "description": "Account line type"
+    },
+    "payment_type": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Payment type"
+    },
+    "amount_outstanding": {
+      "type": "number",
+      "description": "Outstanding amount"
+    },
+    "last_increment": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "The amount the line was increased last time"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Timestamp for the latest line update"
+    },
+    "internal_note": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Internal note"
+    },
+    "staff_id": {
+      "type": "integer",
+      "description": "Internal patron identifier for the staff member that introduced the account line"
+    }
+  }
+}

api/v1/swagger/definitions/patron_balance.json

@@ -0,0 +1,19 @@
+{
+  "type": "object",
+  "properties": {
+    "balance": {
+      "type": "number",
+      "description": "Signed decimal number"
+    },
+    "outstanding_lines": {
+      "type": "array",
+      "items": {
+        "$ref": "account_line.json"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "required": [
+    "balance"
+  ]
+}

api/v1/swagger/paths.json

@@ -26,6 +26,9 @@
   "/patrons/{patron_id}": {
     "$ref": "paths/patrons.json#/~1patrons~1{patron_id}"
   },
+  "/patrons/{patron_id}/account": {
+    "$ref": "paths/patrons_account.json#/~1patrons~1{patron_id}~1account"
+  },
   "/illrequests": {
     "$ref": "paths/illrequests.json#/~1illrequests"
   }

api/v1/swagger/paths/patrons_account.json

@@ -0,0 +1,65 @@
+{
+  "/patrons/{patron_id}/account": {
+    "get": {
+      "x-mojo-to": "Patrons::Account#get",
+      "operationId": "getPatronAccount",
+      "tags": [
+        "patron"
+      ],
+      "parameters": [
+        {
+          "$ref": "../parameters.json#/patron_id_pp"
+        }
+      ],
+      "produces": [
+        "application/json"
+      ],
+      "responses": {
+        "200": {
+          "description": "Patron's account balance",
+          "schema": {
+            "$ref": "../definitions.json#/patron_balance"
+          }
+        },
+        "401": {
+          "description": "Authentication required",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "403": {
+          "description": "Access forbidden",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "404": {
+          "description": "Patron 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": {
+        "allow-owner": true,
+        "allow-guarantor": true,
+        "permissions": {
+          "borrowers": "edit_borrowers",
+          "updatecharges": "remaining_permissions"
+        }
+      }
+    }
+  }
+}