From 3958ab9902c24e841fd0c5e2e03dab592658edb1 Mon Sep 17 00:00:00 2001
From: Tomas Cohen Arazi <tomascohen@theke.io>
Date: Fri, 23 Apr 2021 14:43:31 -0300
Subject: [PATCH] Bug 17314: OpenAPI spec

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
---
 api/v1/swagger/definitions.json            |   3 +
 api/v1/swagger/definitions/suggestion.json | 154 +++++++++++
 api/v1/swagger/parameters.json             |   3 +
 api/v1/swagger/parameters/suggestion.json  |   9 +
 api/v1/swagger/paths.json                  |   6 +
 api/v1/swagger/paths/suggestions.json      | 290 +++++++++++++++++++++
 6 files changed, 465 insertions(+)
 create mode 100644 api/v1/swagger/definitions/suggestion.json
 create mode 100644 api/v1/swagger/parameters/suggestion.json
 create mode 100644 api/v1/swagger/paths/suggestions.json

diff --git a/api/v1/swagger/definitions.json b/api/v1/swagger/definitions.json
index 02dbc95c019..5a01bbfc58c 100644
--- a/api/v1/swagger/definitions.json
+++ b/api/v1/swagger/definitions.json
@@ -88,5 +88,8 @@
   },
   "smtp_server": {
     "$ref": "definitions/smtp_server.json"
+  },
+  "suggestion": {
+    "$ref": "definitions/suggestion.json"
   }
 }
diff --git a/api/v1/swagger/definitions/suggestion.json b/api/v1/swagger/definitions/suggestion.json
new file mode 100644
index 00000000000..3e467b8dd76
--- /dev/null
+++ b/api/v1/swagger/definitions/suggestion.json
@@ -0,0 +1,154 @@
+{
+  "type": "object",
+  "properties": {
+    "suggestion_id": {
+      "type": "string",
+      "readOnly": true,
+      "description": "unique identifier assigned automatically by Koha"
+    },
+    "suggested_by": {
+      "type": ["string", "null"],
+      "description": "patron_id for the person making the suggestion, foreign key linking to the borrowers table"
+    },
+    "suggestion_date": {
+      "type": ["string", "null"],
+      "format": "date",
+      "description": "the suggestion was submitted"
+    },
+    "managed_by": {
+      "type": ["string", "null"],
+      "description": "patron_id for the librarian managing the suggestion, foreign key linking to the borrowers table"
+    },
+    "managed_date": {
+      "type": ["string", "null"],
+      "format": "date",
+      "description": "date the suggestion was updated"
+    },
+    "accepted_by": {
+      "type": ["string", "null"],
+      "description": "patron_id for the librarian who accepted the suggestion, foreign key linking to the borrowers table"
+    },
+    "accepted_date": {
+      "type": ["string", "null"],
+      "format": "date",
+      "description": "date the suggestion was marked as accepted"
+    },
+    "rejected_by": {
+      "type": ["string", "null"],
+      "description": "patron_id for the librarian who rejected the suggestion, foreign key linking to the borrowers table"
+    },
+    "rejected_date": {
+      "type": ["string", "null"],
+      "format": "date",
+      "description": "date the suggestion was marked as rejected"
+    },
+    "last_modification_by": {
+      "type": ["string", "null"],
+      "description": "patron the suggestion was last modified by"
+    },
+    "last_modification_date": {
+      "type": ["string", "null"],
+      "format": "date",
+      "description": "date the suggestion was last modified"
+    },
+    "status": {
+      "type": "string",
+      "description": "Suggestion status",
+      "enum": [
+        "ASKED",
+        "CHECKED",
+        "ACCEPTED",
+        "REJECTED"
+      ]
+    },
+    "note": {
+      "type": ["string", "null"],
+      "description": "note entered on the suggestion"
+    },
+    "author": {
+      "type": ["string", "null"],
+      "description": "author of the suggested item"
+    },
+    "title": {
+      "type": ["string", "null"],
+      "description": "title of the suggested item"
+    },
+    "copyright_date": {
+      "type": ["integer", "null"],
+      "description": "copyright date of the suggested item"
+    },
+    "publisher_code": {
+      "type": ["string", "null"],
+      "description": "publisher of the suggested item"
+    },
+    "date_created": {
+      "type": ["string", "null"],
+      "description": "timestamp of date created"
+    },
+    "volume_desc": {
+      "type": ["string", "null"],
+      "description": "volume description"
+    },
+    "publication_year": {
+      "type": ["string", "null"],
+      "description": "year of publication"
+    },
+    "publication_place": {
+      "type": ["string", "null"],
+      "description": "publication place of the suggested item"
+    },
+    "isbn": {
+      "type": ["string", "null"],
+      "description": "isbn of the suggested item"
+    },
+    "biblio_id": {
+      "type": ["string", "null"],
+      "description": "foreign key linking the suggestion to the biblio table after the suggestion has been ordered"
+    },
+    "reason": {
+      "type": ["string", "null"],
+      "description": "reason for accepting or rejecting the suggestion"
+    },
+    "patron_reason": {
+      "type": ["string", "null"],
+      "description": "reason for making the suggestion"
+    },
+    "budget_id": {
+      "type": ["string", "null"],
+      "description": "foreign key linking the suggested budget to the aqbudgets table"
+    },
+    "library_id": {
+      "type": ["string", "null"],
+      "description": "foreign key linking the suggested branch to the branches table"
+    },
+    "collection_title": {
+      "type": ["string", "null"],
+      "description": "collection name for the suggested item"
+    },
+    "item_type": {
+      "type": ["string", "null"],
+      "description": "suggested item type"
+    },
+    "quantity": {
+      "type": ["string", "null"],
+      "description": "suggested quantity to be purchased"
+    },
+    "currency": {
+      "type": ["string", "null"],
+      "description": "suggested currency for the suggested price"
+    },
+    "item_price": {
+      "type": ["number", "null"],
+      "description": "suggested price"
+    },
+    "total_price": {
+      "type": ["string", "null"],
+      "description": "suggested total cost (price*quantity updated for currency)"
+    },
+    "archived": {
+      "type": ["boolean", "null"],
+      "description": "archived (processed) suggestion"
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/api/v1/swagger/parameters.json b/api/v1/swagger/parameters.json
index 95464e14612..cc8d6186057 100644
--- a/api/v1/swagger/parameters.json
+++ b/api/v1/swagger/parameters.json
@@ -119,5 +119,8 @@
   },
   "fundidPathParam": {
     "$ref": "parameters/fund.json#/fundidPathParam"
+  },
+  "suggestion_id_pp": {
+    "$ref": "parameters/suggestion.json#/suggestion_id_pp"
   }
 }
diff --git a/api/v1/swagger/parameters/suggestion.json b/api/v1/swagger/parameters/suggestion.json
new file mode 100644
index 00000000000..0de69f476f5
--- /dev/null
+++ b/api/v1/swagger/parameters/suggestion.json
@@ -0,0 +1,9 @@
+{
+  "suggestion_id_pp": {
+    "name": "suggestion_id",
+    "in": "path",
+    "description": "Internal suggestion identifier",
+    "required": true,
+    "type": "integer"
+  }
+}
diff --git a/api/v1/swagger/paths.json b/api/v1/swagger/paths.json
index 917100b6708..f41f472a12f 100644
--- a/api/v1/swagger/paths.json
+++ b/api/v1/swagger/paths.json
@@ -181,5 +181,11 @@
   },
   "/return_claims/{claim_id}": {
     "$ref": "paths/return_claims.json#/~1return_claims~1{claim_id}"
+  },
+  "/suggestions": {
+    "$ref": "paths/suggestions.json#/~1suggestions"
+  },
+  "/suggestions/{suggestion_id}": {
+    "$ref": "paths/suggestions.json#/~1suggestions~1{suggestion_id}"
   }
 }
diff --git a/api/v1/swagger/paths/suggestions.json b/api/v1/swagger/paths/suggestions.json
new file mode 100644
index 00000000000..9bca485396c
--- /dev/null
+++ b/api/v1/swagger/paths/suggestions.json
@@ -0,0 +1,290 @@
+{
+  "/suggestions": {
+    "get": {
+      "x-mojo-to": "Suggestions#list",
+      "operationId" : "list",
+      "tags": ["patrons", "suggestions"],
+      "parameters": [
+        {
+          "$ref": "../parameters.json#/match"
+        },
+        {
+          "$ref": "../parameters.json#/order_by"
+        },
+        {
+          "$ref": "../parameters.json#/page"
+        },
+        {
+          "$ref": "../parameters.json#/per_page"
+        },
+        {
+          "$ref": "../parameters.json#/q_param"
+        },
+        {
+          "$ref": "../parameters.json#/q_body"
+        },
+        {
+          "$ref": "../parameters.json#/q_header"
+        }
+      ],
+      "produces": [
+          "application/json"
+      ],
+      "responses": {
+        "200": {
+          "description": "A list of suggestions",
+          "schema": {
+            "type": "array",
+            "items": {
+              "$ref": "../definitions.json#/suggestion"
+            }
+          }
+        },
+        "403": {
+          "description": "Access forbidden",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "500": {
+          "description": "Internal error",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "503": {
+          "description": "Under maintenance",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        }
+      },
+      "x-koha-authorization": {
+        "permissions": {
+          "suggestions": "suggestions_manage"
+        }
+      }
+    },
+    "post": {
+      "x-mojo-to": "Suggestions#add",
+      "operationId": "add",
+      "tags": ["patrons", "suggestions"],
+      "parameters": [{
+        "name": "body",
+        "in": "body",
+        "description": "A JSON object containing informations about the new suggestion",
+        "required": true,
+        "schema": {
+          "$ref": "../definitions.json#/suggestion"
+        }
+      }],
+      "produces": [
+        "application/json"
+      ],
+      "responses": {
+        "201": {
+          "description": "Suggestion added",
+          "schema": {
+            "$ref": "../definitions.json#/suggestion"
+          }
+        },
+        "400": {
+          "description": "Bad request",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "403": {
+          "description": "Access forbidden",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "500": {
+          "description": "Internal error",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "503": {
+          "description": "Under maintenance",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        }
+      },
+      "x-koha-authorization": {
+        "permissions": {
+          "suggestions": "suggestions_manage"
+        }
+      }
+    }
+  },
+  "/suggestions/{suggestion_id}": {
+    "get": {
+      "x-mojo-to": "Suggestions#get",
+      "operationId": "getSuggestions",
+      "tags": ["patrons", "suggestions"],
+      "parameters": [{
+          "$ref": "../parameters.json#/suggestion_id_pp"
+        }
+      ],
+      "produces": [
+          "application/json"
+      ],
+      "responses": {
+        "200": {
+          "description": "A suggestion",
+          "schema": {
+            "$ref": "../definitions.json#/suggestion"
+          }
+        },
+        "403": {
+          "description": "Access forbidden",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "404": {
+          "description": "Suggestion not found",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "500": {
+          "description": "Internal error",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "503": {
+          "description": "Under maintenance",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        }
+      },
+      "x-koha-authorization": {
+        "permissions": {
+          "suggestions": "suggestions_manage"
+        }
+      }
+    },
+    "put": {
+      "x-mojo-to": "Suggestions#update",
+      "operationId": "update",
+      "tags": ["patrons", "suggestions"],
+      "parameters": [{
+        "$ref": "../parameters.json#/suggestion_id_pp"
+      }, {
+        "name": "body",
+        "in": "body",
+        "description": "A JSON object containing informations about the new hold",
+        "required": true,
+        "schema": {
+          "$ref": "../definitions.json#/suggestion"
+        }
+      }],
+      "produces": [
+        "application/json"
+      ],
+      "responses": {
+        "200": {
+          "description": "A suggestion",
+          "schema": {
+            "$ref": "../definitions.json#/suggestion"
+          }
+        },
+        "400": {
+          "description": "Bad request",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "403": {
+          "description": "Access forbidden",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "404": {
+          "description": "Suggestion not found",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "500": {
+          "description": "Internal error",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "503": {
+          "description": "Under maintenance",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        }
+      },
+      "x-koha-authorization": {
+        "permissions": {
+          "suggestions": "suggestions_manage"
+        }
+      }
+    },
+    "delete": {
+      "x-mojo-to": "Suggestions#delete",
+      "operationId": "delete",
+      "tags": ["patrons", "suggestions"],
+      "parameters": [{
+        "$ref": "../parameters.json#/suggestion_id_pp"
+      }],
+      "produces": [
+        "application/json"
+      ],
+      "responses": {
+        "204": {
+          "description": "Suggestion deleted",
+          "schema": {
+            "type": "string"
+          }
+        },
+        "401": {
+          "description": "Authentication required",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "403": {
+          "description": "Access forbidden",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "404": {
+          "description": "Suggestion not found",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "500": {
+          "description": "Internal error",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "503": {
+          "description": "Under maintenance",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        }
+      },
+      "x-koha-authorization": {
+        "permissions": {
+          "suggestions": "suggestions_manage"
+        }
+      }
+    }
+  }
+}
-- 
2.31.1