Koha/api/v1/swagger/paths/biblios.yaml
Tomas Cohen Arazi b7b6a85de5 Bug 28020: (follow-up) Add docs about error_code on the API
This patch intends to be a guide for inserting Markdown documentation
for error codes. The idea is that it can be copied and pasted as-is in
new routes. And adapted to new error codes.

To test:
1. Apply this patch
2. Run:
   $ npx redoc-cli@0.10.4 bundle --cdn --output index.html \
            api/v1/swagger/swagger.yaml
=> SUCCESS: It builds correctly
3. Open index.tml on your browser
4. Pick a route, and see the 500 status description includes information
   about the possible `error_code` values.
5. Sign off :-D

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Andrew Fuerste-Henry <andrew@bywatersolutions.com>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Signed-off-by: Fridolin Somers <fridolin.somers@biblibre.com>
2022-01-05 13:33:46 -10:00

375 lines
10 KiB
YAML

---
"/biblios/{biblio_id}":
get:
x-mojo-to: Biblios#get
operationId: getBiblio
tags:
- biblios
summary: Get biblio
parameters:
- $ref: ../parameters.yaml#/biblio_id_pp
produces:
- application/json
- application/marcxml+xml
- application/marc-in-json
- application/marc
- text/plain
responses:
"200":
description: A biblio
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Access forbidden
schema:
$ref: ../definitions.yaml#/error
"404":
description: Biblio not found
schema:
$ref: ../definitions.yaml#/error
"406":
description: Not acceptable
schema:
type: array
description: Accepted content-types
items:
type: string
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/error
x-koha-authorization:
permissions:
catalogue: "1"
delete:
x-mojo-to: Biblios#delete
operationId: deleteBiblio
tags:
- biblios
summary: Delete biblio
parameters:
- $ref: ../parameters.yaml#/biblio_id_pp
produces:
- application/json
responses:
"204":
description: Biblio deleted
schema:
type: string
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Access forbidden
schema:
$ref: ../definitions.yaml#/error
"404":
description: Biblio not found
schema:
$ref: ../definitions.yaml#/error
"409":
description: Unable to perform action on biblio
schema:
$ref: ../definitions.yaml#/error
"500":
description: Internal error
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/error
x-koha-authorization:
permissions:
editcatalogue: edit_catalogue
"/biblios/{biblio_id}/checkouts":
get:
x-mojo-to: Biblios#get_checkouts
operationId: listBiblioCheckouts
tags:
- checkouts
summary: List checkouts for a biblio
parameters:
- $ref: ../parameters.yaml#/biblio_id_pp
- $ref: ../parameters.yaml#/page
- $ref: ../parameters.yaml#/per_page
- $ref: ../parameters.yaml#/match
- $ref: ../parameters.yaml#/order_by
- $ref: ../parameters.yaml#/q_param
- $ref: ../parameters.yaml#/q_body
- $ref: ../parameters.yaml#/q_header
- name: checked_in
in: query
description: By default, current checkouts are returned, when this is true then
checked in checkouts are returned as result.
type: boolean
produces:
- application/json
responses:
"200":
description: A list of checkouts
schema:
$ref: ../definitions.yaml#/checkouts
"403":
description: Access forbidden
schema:
$ref: ../definitions.yaml#/error
"404":
description: Biblio not found
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/error
x-koha-authorization:
permissions:
circulate: circulate_remaining_permissions
x-koha-embed:
- issuer
- item
- patron
- library
"/biblios/{biblio_id}/items":
get:
x-mojo-to: Biblios#get_items
operationId: getBiblioItems
tags:
- biblios
summary: Get items for a biblio
parameters:
- $ref: ../parameters.yaml#/biblio_id_pp
- $ref: ../parameters.yaml#/match
- $ref: ../parameters.yaml#/order_by
- $ref: ../parameters.yaml#/page
- $ref: ../parameters.yaml#/per_page
- $ref: ../parameters.yaml#/q_param
- $ref: ../parameters.yaml#/q_body
- $ref: ../parameters.yaml#/q_header
consumes:
- application/json
produces:
- application/json
responses:
"200":
description: A list of the items attached to the record
schema:
type: array
items:
$ref: ../definitions.yaml#/item
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Access forbidden
schema:
$ref: ../definitions.yaml#/error
"404":
description: Biblio not found
schema:
$ref: ../definitions.yaml#/error
"406":
description: Not acceptable
schema:
type: array
description: Accepted content-types
items:
type: string
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/error
x-koha-authorization:
permissions:
catalogue: "1"
"/biblios/{biblio_id}/pickup_locations":
get:
x-mojo-to: Biblios#pickup_locations
operationId: getBiblioPickupLocations
tags:
- biblios
summary: Get valid pickup locations for a biblio
parameters:
- $ref: ../parameters.yaml#/biblio_id_pp
- name: patron_id
in: query
description: Internal patron identifier
required: true
type: integer
- $ref: ../parameters.yaml#/match
- $ref: ../parameters.yaml#/order_by
- $ref: ../parameters.yaml#/page
- $ref: ../parameters.yaml#/per_page
- $ref: ../parameters.yaml#/q_param
- $ref: ../parameters.yaml#/q_body
- $ref: ../parameters.yaml#/q_header
consumes:
- application/json
produces:
- application/json
responses:
"200":
description: Biblio pickup locations
schema:
type: array
items:
$ref: ../definitions.yaml#/library
"400":
description: Missing or wrong parameters
schema:
$ref: ../definitions.yaml#/error
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Access forbidden
schema:
$ref: ../definitions.yaml#/error
"404":
description: Biblio not found
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/error
x-koha-authorization:
permissions:
reserveforothers: place_holds
"/public/biblios/{biblio_id}":
get:
x-mojo-to: Biblios#get_public
operationId: getBiblioPublic
tags:
- biblios
summary: Get biblio (public)
parameters:
- $ref: ../parameters.yaml#/biblio_id_pp
produces:
- application/marcxml+xml
- application/marc-in-json
- application/marc
- text/plain
responses:
"200":
description: A biblio
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Access forbidden
schema:
$ref: ../definitions.yaml#/error
"404":
description: Biblio not found
schema:
$ref: ../definitions.yaml#/error
"406":
description: Not acceptable
schema:
type: array
description: Accepted content-types
items:
type: string
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/error
"/public/biblios/{biblio_id}/items":
get:
x-mojo-to: Biblios#get_items_public
operationId: getBiblioItemsPublic
tags:
- biblios
- items
parameters:
- $ref: ../parameters.yaml#/biblio_id_pp
- $ref: ../parameters.yaml#/match
- $ref: ../parameters.yaml#/order_by
- $ref: ../parameters.yaml#/page
- $ref: ../parameters.yaml#/per_page
- $ref: ../parameters.yaml#/q_param
- $ref: ../parameters.yaml#/q_body
- $ref: ../parameters.yaml#/q_header
consumes:
- application/json
produces:
- application/json
responses:
"200":
description: A list of the items attached to the record
schema:
type: array
items:
$ref: ../definitions.yaml#/item
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Access forbidden
schema:
$ref: ../definitions.yaml#/error
"404":
description: Biblio not found
schema:
$ref: ../definitions.yaml#/error
"406":
description: Not acceptable
schema:
type: array
description: Accepted content-types
items:
type: string
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/error