Bug 17314: OpenAPI spec

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>

api/v1/swagger/definitions.json

@@ -88,5 +88,8 @@
   },
   "smtp_server": {
     "$ref": "definitions/smtp_server.json"
+  },
+  "suggestion": {
+    "$ref": "definitions/suggestion.yaml"
   }
 }

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

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"
   }
 }

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"
+  }
+}

api/v1/swagger/paths.json

@@ -193,5 +193,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}"
   }
 }

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

api/v1/swagger/swagger.yaml

@@ -144,6 +144,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: |