Bug 29108: Add q parameters to items routes

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

@@ -26,6 +26,9 @@
   "invoice": {
     "$ref": "definitions/invoice.json"
   },
+  "item": {
+    "$ref": "definitions/item.yaml"
+  },
   "checkouts": {
     "$ref": "definitions/checkouts.json"
   },
@@ -53,9 +56,6 @@
   "transfer_limit": {
     "$ref": "definitions/transfer_limit.json"
   },
-  "item": {
-    "$ref": "definitions/item.json"
-  },
   "order": {
     "$ref": "definitions/order.json"
   },

api/v1/swagger/definitions/item.json

@@ -1,187 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "item_id": {
-      "type": "integer",
-      "description": "Internal item identifier"
-    },
-    "biblio_id": {
-      "type": "integer",
-      "description": "Internal identifier for the parent bibliographic record"
-    },
-    "external_id": {
-      "type": ["string", "null"],
-      "description": "The item's barcode"
-    },
-    "acquisition_date": {
-      "type": ["string", "null"],
-      "format": "date",
-      "description": "The date the item was acquired"
-    },
-    "acquisition_source": {
-      "type": ["string", "null"],
-      "description": "Information about the acquisition source (it is not really a vendor id)"
-    },
-    "home_library_id": {
-      "type": ["string", "null"],
-      "description": "Internal library id for the library the item belongs to"
-    },
-    "purchase_price": {
-      "type": ["number", "null"],
-      "description": "Purchase price"
-    },
-    "replacement_price": {
-      "type": ["number", "null"],
-      "description": "Cost the library charges to replace the item (e.g. if lost)"
-    },
-    "replacement_price_date": {
-      "type": ["string", "null"],
-      "format": "date",
-      "description": "The date the replacement price is effective from"
-    },
-    "last_checkout_date": {
-      "type": ["string", "null"],
-      "format": "date",
-      "description": "The date the item was last checked out"
-    },
-    "last_seen_date": {
-      "type": ["string", "null"],
-      "format": "date",
-      "description": "The date the item barcode was last scanned"
-    },
-    "not_for_loan_status": {
-      "type": "integer",
-      "description": "Authorized value defining why this item is not for loan"
-    },
-    "damaged_status": {
-      "type": "integer",
-      "description": "Authorized value defining this item as damaged"
-    },
-    "damaged_date": {
-      "type": ["string", "null"],
-      "description": "The date and time an item was last marked as damaged, NULL if not damaged"
-    },
-    "lost_status": {
-      "type": "integer",
-      "description": "Authorized value defining this item as lost"
-    },
-    "lost_date": {
-      "type": ["string", "null"],
-      "format": "date-time",
-      "description": "The date and time an item was last marked as lost, NULL if not lost"
-    },
-    "withdrawn": {
-      "type": "integer",
-      "description": "Authorized value defining this item as withdrawn"
-    },
-    "withdrawn_date": {
-      "type": ["string", "null"],
-      "format": "date-time",
-      "description": "The date and time an item was last marked as withdrawn, NULL if not withdrawn"
-    },
-    "callnumber": {
-      "type": ["string", "null"],
-      "description": "Call number for this item"
-    },
-    "coded_location_qualifier": {
-      "type": ["string", "null"],
-      "description": "Coded location qualifier"
-    },
-    "checkouts_count": {
-      "type": ["integer", "null"],
-      "description": "Number of times this item has been checked out/issued"
-    },
-    "renewals_count": {
-      "type": ["integer", "null"],
-      "description": "Number of times this item has been renewed"
-    },
-    "holds_count": {
-      "type": ["integer", "null"],
-      "description": "Number of times this item has been placed on hold/reserved"
-    },
-    "restricted_status": {
-      "type": ["integer", "null"],
-      "description": "Authorized value defining use restrictions for this item"
-    },
-    "public_notes": {
-      "type": ["string", "null"],
-      "description": "Public notes on this item"
-    },
-    "internal_notes": {
-      "type": ["string", "null"],
-      "description": "Non-public notes on this item"
-    },
-    "holding_library_id": {
-      "type": ["string", "null"],
-      "description": "Library that is currently in possession item"
-    },
-    "timestamp": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Date and time this item was last altered"
-    },
-    "location": {
-      "type": ["string", "null"],
-      "description": "Authorized value for the shelving location for this item"
-    },
-    "permanent_location": {
-      "type": ["string", "null"],
-      "description": "Linked to the CART and PROC temporary locations feature, stores the permanent shelving location"
-    },
-    "checked_out_date": {
-      "type": ["string", "null"],
-      "format": "date",
-      "description": "Defines if item is checked out (NULL for not checked out, and checkout date for checked out)"
-    },
-    "call_number_source": {
-      "type": ["string", "null"],
-      "description": "Classification source used on this item"
-    },
-    "call_number_sort": {
-      "type": ["string", "null"],
-      "description": "?"
-    },
-    "collection_code": {
-      "type": ["string", "null"],
-      "description": "Authorized value for the collection code associated with this item"
-    },
-    "materials_notes": {
-      "type": ["string", "null"],
-      "description": "Materials specified"
-    },
-    "uri": {
-      "type": ["string", "null"],
-      "description": "URL for the item"
-    },
-    "item_type_id": {
-      "type": ["string", "null"],
-      "description": "Itemtype defining the type for this item"
-    },
-    "extended_subfields": {
-      "type": ["string", "null"],
-      "description": "Additional 952 subfields in XML format"
-    },
-    "serial_issue_number": {
-      "type": ["string", "null"],
-      "description": "serial enumeration/chronology for the item"
-    },
-    "copy_number": {
-      "type": ["string", "null"],
-      "description": "Copy number"
-    },
-    "inventory_number": {
-      "type": ["string", "null"],
-      "description": "Inventory number"
-    },
-    "new_status": {
-      "type": ["string", "null"],
-      "description": "'new' value, whatever free-text information."
-    },
-    "exclude_from_local_holds_priority": {
-      "type": "boolean",
-      "description": "Exclude this item from local holds priority."
-    }
-  },
-  "additionalProperties": false,
-  "required": ["item_id", "biblio_id", "not_for_loan_status", "damaged_status", "lost_status", "withdrawn"]
-}

api/v1/swagger/definitions/item.yaml

@@ -0,0 +1,221 @@
+---
+type: object
+properties:
+  item_id:
+    type: integer
+    description: Internal item identifier
+  biblio_id:
+    type: integer
+    description: Internal identifier for the parent bibliographic record
+  external_id:
+    type:
+      - string
+      - "null"
+    description: The item's barcode
+  acquisition_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: The date the item was acquired
+  acquisition_source:
+    type:
+      - string
+      - "null"
+    description: Information about the acquisition source (it is not really a vendor id)
+  home_library_id:
+    type:
+      - string
+      - "null"
+    description: Internal library id for the library the item belongs to
+  purchase_price:
+    type:
+      - number
+      - "null"
+    description: Purchase price
+  replacement_price:
+    type:
+      - number
+      - "null"
+    description: Cost the library charges to replace the item (e.g. if lost)
+  replacement_price_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: The date the replacement price is effective from
+  last_checkout_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: The date the item was last checked out
+  last_seen_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: The date the item barcode was last scanned
+  not_for_loan_status:
+    type: integer
+    description: Authorized value defining why this item is not for loan
+  damaged_status:
+    type: integer
+    description: Authorized value defining this item as damaged
+  damaged_date:
+    type:
+      - string
+      - "null"
+    description: The date and time an item was last marked as damaged, NULL if not damaged
+  lost_status:
+    type: integer
+    description: Authorized value defining this item as lost
+  lost_date:
+    type:
+      - string
+      - "null"
+    format: date-time
+    description: The date and time an item was last marked as lost, NULL if not lost
+  withdrawn:
+    type: integer
+    description: Authorized value defining this item as withdrawn
+  withdrawn_date:
+    type:
+      - string
+      - "null"
+    format: date-time
+    description: The date and time an item was last marked as withdrawn, NULL if not
+      withdrawn
+  callnumber:
+    type:
+      - string
+      - "null"
+    description: Call number for this item
+  coded_location_qualifier:
+    type:
+      - string
+      - "null"
+    description: Coded location qualifier
+  checkouts_count:
+    type:
+      - integer
+      - "null"
+    description: Number of times this item has been checked out/issued
+  renewals_count:
+    type:
+      - integer
+      - "null"
+    description: Number of times this item has been renewed
+  holds_count:
+    type:
+      - integer
+      - "null"
+    description: Number of times this item has been placed on hold/reserved
+  restricted_status:
+    type:
+      - integer
+      - "null"
+    description: Authorized value defining use restrictions for this item
+  public_notes:
+    type:
+      - string
+      - "null"
+    description: Public notes on this item
+  internal_notes:
+    type:
+      - string
+      - "null"
+    description: Non-public notes on this item
+  holding_library_id:
+    type:
+      - string
+      - "null"
+    description: Library that is currently in possession item
+  timestamp:
+    type: string
+    format: date-time
+    description: Date and time this item was last altered
+  location:
+    type:
+      - string
+      - "null"
+    description: Authorized value for the shelving location for this item
+  permanent_location:
+    type:
+      - string
+      - "null"
+    description: Linked to the CART and PROC temporary locations feature, stores the
+      permanent shelving location
+  checked_out_date:
+    type:
+      - string
+      - "null"
+    format: date
+    description: Defines if item is checked out (NULL for not checked out, and checkout
+      date for checked out)
+  call_number_source:
+    type:
+      - string
+      - "null"
+    description: Classification source used on this item
+  call_number_sort:
+    type:
+      - string
+      - "null"
+    description: "?"
+  collection_code:
+    type:
+      - string
+      - "null"
+    description: Authorized value for the collection code associated with this item
+  materials_notes:
+    type:
+      - string
+      - "null"
+    description: Materials specified
+  uri:
+    type:
+      - string
+      - "null"
+    description: URL for the item
+  item_type_id:
+    type:
+      - string
+      - "null"
+    description: Itemtype defining the type for this item
+  extended_subfields:
+    type:
+      - string
+      - "null"
+    description: Additional 952 subfields in XML format
+  serial_issue_number:
+    type:
+      - string
+      - "null"
+    description: serial enumeration/chronology for the item
+  copy_number:
+    type:
+      - string
+      - "null"
+    description: Copy number
+  inventory_number:
+    type:
+      - string
+      - "null"
+    description: Inventory number
+  new_status:
+    type:
+      - string
+      - "null"
+    description: "'new' value, whatever free-text information."
+  exclude_from_local_holds_priority:
+    type: boolean
+    description: Exclude this item from local holds priority.
+additionalProperties: false
+required:
+  - item_id
+  - biblio_id
+  - not_for_loan_status
+  - damaged_status
+  - lost_status
+  - withdrawn

api/v1/swagger/paths.json

@@ -81,13 +81,13 @@
     "$ref": "paths/holds.json#/~1holds~1{hold_id}~1pickup_location"
   },
   "/items": {
-    "$ref": "paths/items.json#/~1items"
+    "$ref": "paths/items.yaml#/~1items"
   },
   "/items/{item_id}": {
-    "$ref": "paths/items.json#/~1items~1{item_id}"
+    "$ref": "paths/items.yaml#/~1items~1{item_id}"
   },
   "/items/{item_id}/pickup_locations": {
-    "$ref": "paths/items.json#/~1items~1{item_id}~1pickup_locations"
+    "$ref": "paths/items.yaml#/~1items~1{item_id}~1pickup_locations"
   },
   "/libraries": {
     "$ref": "paths/libraries.json#/~1libraries"

api/v1/swagger/paths/items.json

@@ -1,238 +0,0 @@
-{
-  "/items": {
-    "get": {
-      "x-mojo-to": "Items#list",
-      "operationId": "listItems",
-      "tags": [
-        "items"
-      ],
-      "summary": "List items",
-      "parameters": [
-        {
-          "name": "external_id",
-          "in": "query",
-          "description": "Search on the item's barcode",
-          "required": false,
-          "type": "string"
-        },
-        {
-          "$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"
-        }
-      ],
-      "consumes": [
-        "application/json"
-      ],
-      "produces": [
-        "application/json"
-      ],
-      "responses": {
-        "200": {
-          "description": "A list of item",
-          "schema": {
-            "type": "array",
-            "items": {
-              "$ref": "../definitions.json#/item"
-            }
-          }
-        },
-        "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": {
-          "catalogue": "1"
-        }
-      }
-    }
-  },
-  "/items/{item_id}": {
-    "get": {
-      "x-mojo-to": "Items#get",
-      "operationId": "getItem",
-      "tags": ["items"],
-      "summary": "Get item",
-      "parameters": [{
-          "$ref": "../parameters.json#/item_id_pp"
-        }
-      ],
-      "consumes": ["application/json"],
-      "produces": ["application/json"],
-      "responses": {
-        "200": {
-          "description": "An item",
-          "schema": {
-            "$ref": "../definitions.json#/item"
-          }
-        },
-        "400": {
-          "description": "Missing or wrong parameters",
-          "schema": {
-            "$ref": "../definitions.json#/error"
-          }
-        },
-        "404": {
-          "description": "Item 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": {
-          "catalogue": "1"
-        }
-      }
-    }
-  },
-  "/items/{item_id}/pickup_locations": {
-    "get": {
-      "x-mojo-to": "Items#pickup_locations",
-      "operationId": "getItemPickupLocations",
-      "summary": "Get valid pickup locations for an item",
-      "tags": ["items"],
-      "parameters": [
-        {
-          "$ref": "../parameters.json#/item_id_pp"
-        },
-        {
-          "name": "patron_id",
-          "in": "query",
-          "description": "Internal patron identifier",
-          "required": true,
-          "type": "integer"
-        },
-        {
-          "$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"
-        }
-      ],
-      "consumes": [
-        "application/json"
-      ],
-      "produces": [
-        "application/json"
-      ],
-      "responses": {
-        "200": {
-          "description": "Item pickup locations",
-          "schema": {
-            "type": "array",
-            "items": {
-              "$ref": "../definitions.json#/library"
-            }
-          }
-        },
-        "400": {
-          "description": "Missing or wrong parameters",
-          "schema": {
-            "$ref": "../definitions.json#/error"
-          }
-        },
-        "401": {
-          "description": "Authentication required",
-          "schema": {
-            "$ref": "../definitions.json#/error"
-          }
-        },
-        "403": {
-          "description": "Access forbidden",
-          "schema": {
-            "$ref": "../definitions.json#/error"
-          }
-        },
-        "404": {
-          "description": "Biblio 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": {
-          "reserveforothers": "place_holds"
-        }
-      }
-    }
-  }
-}

api/v1/swagger/paths/items.yaml

@@ -0,0 +1,147 @@
+---
+/items:
+  get:
+    x-mojo-to: Items#list
+    operationId: listItems
+    tags:
+      - items
+    summary: List items
+    parameters:
+      - name: external_id
+        in: query
+        description: Search on the item's barcode
+        required: false
+        type: string
+      - $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
+    consumes:
+      - application/json
+    produces:
+      - application/json
+    responses:
+      "200":
+        description: A list of item
+        schema:
+          type: array
+          items:
+            $ref: ../definitions.json#/item
+      "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:
+        catalogue: "1"
+"/items/{item_id}":
+  get:
+    x-mojo-to: Items#get
+    operationId: getItem
+    tags:
+      - items
+    summary: Get item
+    parameters:
+      - $ref: ../parameters.json#/item_id_pp
+    consumes:
+      - application/json
+    produces:
+      - application/json
+    responses:
+      "200":
+        description: An item
+        schema:
+          $ref: ../definitions.json#/item
+      "400":
+        description: Missing or wrong parameters
+        schema:
+          $ref: ../definitions.json#/error
+      "404":
+        description: Item 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:
+        catalogue: "1"
+"/items/{item_id}/pickup_locations":
+  get:
+    x-mojo-to: Items#pickup_locations
+    operationId: getItemPickupLocations
+    summary: Get valid pickup locations for an item
+    tags:
+      - items
+    parameters:
+      - $ref: ../parameters.json#/item_id_pp
+      - name: patron_id
+        in: query
+        description: Internal patron identifier
+        required: true
+        type: integer
+      - $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
+    consumes:
+      - application/json
+    produces:
+      - application/json
+    responses:
+      "200":
+        description: Item pickup locations
+        schema:
+          type: array
+          items:
+            $ref: ../definitions.json#/library
+      "400":
+        description: Missing or wrong parameters
+        schema:
+          $ref: ../definitions.json#/error
+      "401":
+        description: Authentication required
+        schema:
+          $ref: ../definitions.json#/error
+      "403":
+        description: Access forbidden
+        schema:
+          $ref: ../definitions.json#/error
+      "404":
+        description: Biblio 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:
+        reserveforothers: place_holds