From 58c646072c74022a0a106c8389a8d9bd1cb99321 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>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
---
 api/v1/swagger/definitions.json            |   3 +
 api/v1/swagger/definitions/suggestion.yaml | 185 +++++++++++++++++++
 api/v1/swagger/parameters.json             |   3 +
 api/v1/swagger/parameters/suggestion.json  |   9 +
 api/v1/swagger/paths.json                  |   6 +
 api/v1/swagger/paths/suggestions.yaml      | 201 +++++++++++++++++++++
 api/v1/swagger/swagger.yaml                |   4 +
 7 files changed, 411 insertions(+)
 create mode 100644 api/v1/swagger/definitions/suggestion.yaml
 create mode 100644 api/v1/swagger/parameters/suggestion.json
 create mode 100644 api/v1/swagger/paths/suggestions.yaml

diff --git a/api/v1/swagger/definitions.json b/api/v1/swagger/definitions.json
index 02dbc95c019..5eb49b6cccf 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.yaml"
   }
 }
diff --git a/api/v1/swagger/definitions/suggestion.yaml b/api/v1/swagger/definitions/suggestion.yaml
new file mode 100644
index 00000000000..e09f4452968
--- /dev/null
+++ b/api/v1/swagger/definitions/suggestion.yaml
@@ -0,0 +1,185 @@
+---
+type: object
+properties:
+  suggestion_id:
+    type: integer
+    readOnly: true
+    description: unique identifier assigned automatically by Koha
+  suggested_by:
+    type:
+      - integer
+      - "null"
+    description: patron_id for the person making the suggestion, foreign key linking to the
+      borrowers table
+  suggestion_date:
+    type: string
+    format: date
+    description: the suggestion was submitted
+  managed_by:
+    type:
+      - integer
+      - "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:
+      - integer
+      - "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:
+      - integer
+      - "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_status_change_by:
+    type:
+      - integer
+      - "null"
+    description: patron the suggestion was last modified by
+  last_status_change_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
+  timestamp:
+    type:
+      - string
+      - "null"
+    format: date-time
+    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:
+      - integer
+      - "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:
+      - integer
+      - "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 cdcd0368c52..7f19aa84214 100644
--- a/api/v1/swagger/paths.json
+++ b/api/v1/swagger/paths.json
@@ -187,5 +187,11 @@
   },
   "/return_claims/{claim_id}": {
     "$ref": "paths/return_claims.json#/~1return_claims~1{claim_id}"
+  },
+  "/suggestions": {
+    "$ref": "paths/suggestions.yaml#/~1suggestions"
+  },
+  "/suggestions/{suggestion_id}": {
+    "$ref": "paths/suggestions.yaml#/~1suggestions~1{suggestion_id}"
   }
 }
diff --git a/api/v1/swagger/paths/suggestions.yaml b/api/v1/swagger/paths/suggestions.yaml
new file mode 100644
index 00000000000..a8e31bba309
--- /dev/null
+++ b/api/v1/swagger/paths/suggestions.yaml
@@ -0,0 +1,201 @@
+---
+/suggestions:
+  get:
+    x-mojo-to: Suggestions#list
+    operationId: listSuggestions
+    description: This resource returns a list of purchase suggestions
+    summary: List purchase suggestions
+    tags:
+      - 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: addSuggestions
+    description: This resource accepts a new purchase suggestion and creates it
+    summary: Add a purchase suggestion
+    tags:
+      - 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: getSuggestion
+    description: This resource gives access to a specific purchase suggestion
+    summary: Get purchase suggestion
+    tags:
+      - 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: updateSuggestion
+    description: This resource allows updating an existing purchase suggestion
+    summary: Update purchase suggestion
+    tags:
+      - 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: deleteSuggestion
+    description: This resource deletes an existing purchase suggestion
+    summary: Delete purchase suggestion
+    tags:
+      - 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
diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml
index 2e4e9bc09f2..6519c9286d0 100644
--- a/api/v1/swagger/swagger.yaml
+++ b/api/v1/swagger/swagger.yaml
@@ -115,6 +115,10 @@ tags:
     x-displayName: Transfer limits
     description: |
       Manage transfer limits
+  - name: "suggestions"
+    x-displayName: "Purchase suggestions"
+    description: |
+      Manage purchase suggestions
   - name: "vendors"
     x-displayName: "Vendors"
     description: |
-- 
2.20.1