Tomas Cohen Arazi
355d7dc52c
This patch aims to make our API docs be more consistent.
It addresses two particular things:
* There's no consistency on the `tags` used across the spec, and not all
of them are correctly described and have an `x-displayName` entry.
More on this later.
* This are not sorted either by some for of grouping, or at least
alphabetically.
For the former, I did my best trying to harmonize (specially on the ERM
front) with what we do in the rest of the use cases.
For the latter, I opted for sorting everything alphabetically, as a
first step. Hoping someone else could work on grouping things.
To test (ON YOUR HOST MACHINE):
1. On current master run:
$ cd api/v1/swagger
$ docker run --rm -v $(pwd):/api --workdir /api redocly/cli \
build-docs swagger.yaml --output index.html
=> SUCCESS: It doesn't break or anything
2. Open your browser, open the generated api/v1/swagger/index.html file
=> FAIL: The left column has
* several lower case entries
* not everything is correctly grouped (ERM? packages?)
* Things are not sorted. There's an attempt but looks messy
3. Apply this patch
4. Repeat 1 and 2
=> SUCCESS: Things look much better!
5. Sign off :-D
CAVEAT1: I'm not sure why, but import_batches doesn't work. Ideas are
welcome, I'll keep looking for fixes.
CAVEAT2: I don't have enough eHoldings background to weight in, but I
feel like 'ERM eHoldings packages' could just be 'ERM packages'.
Follw-up patches with better ideas are welcome.
CAVEAT3: Patron credits, debits, balance... They could all go in to
'Patrons accounts' or similar. Open to ideas.
CAVEAT4: Old redocly didn't support mapping an endpoint to more than one
target section. Something to explore if we want (for example) to reach
'credits' through the 'Patrons' section but also from 'Accounting'.
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
496 lines
15 KiB
YAML
496 lines
15 KiB
YAML
---
|
|
/erm/eholdings/{provider}/titles:
|
|
get:
|
|
x-mojo-to: ERM::EHoldings::Titles#list
|
|
operationId: listErmEHoldingsTitles
|
|
tags:
|
|
- erm_eholdings_titles
|
|
summary: List eholdings titles
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- description: Provider name
|
|
in: path
|
|
name: provider
|
|
required: true
|
|
type: string
|
|
- description: Case insensitive search on title title_id
|
|
in: query
|
|
name: title_id
|
|
required: false
|
|
type: integer
|
|
- description: Case insensitive search on title publication_title
|
|
in: query
|
|
name: publication_title
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title external_id
|
|
in: query
|
|
name: external_id
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title print_identifier
|
|
in: query
|
|
name: print_identifier
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title online_identifier
|
|
in: query
|
|
name: online_identifier
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title date_first_issue_online
|
|
in: query
|
|
name: date_first_issue_online
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title num_first_vol_online
|
|
in: query
|
|
name: num_first_vol_online
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title num_first_issue_online
|
|
in: query
|
|
name: num_first_issue_online
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title date_last_issue_online
|
|
in: query
|
|
name: date_last_issue_online
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title num_last_vol_online
|
|
in: query
|
|
name: num_last_vol_online
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title num_last_issue_online
|
|
in: query
|
|
name: num_last_issue_online
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title title_url
|
|
in: query
|
|
name: title_url
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title first_author
|
|
in: query
|
|
name: first_author
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title embargo_info
|
|
in: query
|
|
name: embargo_info
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title coverage_depth
|
|
in: query
|
|
name: coverage_depth
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title notes
|
|
in: query
|
|
name: notes
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title publisher_name
|
|
in: query
|
|
name: publisher_name
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title publication_type
|
|
in: query
|
|
name: publication_type
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title date_monograph_published_print
|
|
in: query
|
|
name: date_monograph_published_print
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title date_monograph_published_online
|
|
in: query
|
|
name: date_monograph_published_online
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title monograph_volume
|
|
in: query
|
|
name: monograph_volume
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title monograph_edition
|
|
in: query
|
|
name: monograph_edition
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title first_editor
|
|
in: query
|
|
name: first_editor
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title parent_publication_title_id
|
|
in: query
|
|
name: parent_publication_title_id
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title preceeding_publication_title_id
|
|
in: query
|
|
name: preceeding_publication_title_id
|
|
required: false
|
|
type: string
|
|
- description: Case insensitive search on title access_type
|
|
in: query
|
|
name: access_type
|
|
required: false
|
|
type: string
|
|
- name: x-koha-embed
|
|
in: header
|
|
required: false
|
|
description: Embed list sent as a request header
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum:
|
|
- resources.package
|
|
collectionFormat: csv
|
|
- $ref: "../swagger.yaml#/parameters/match"
|
|
- $ref: "../swagger.yaml#/parameters/order_by"
|
|
- $ref: "../swagger.yaml#/parameters/page"
|
|
- $ref: "../swagger.yaml#/parameters/per_page"
|
|
- $ref: "../swagger.yaml#/parameters/q_param"
|
|
- $ref: "../swagger.yaml#/parameters/q_body"
|
|
- $ref: "../swagger.yaml#/parameters/q_header"
|
|
responses:
|
|
200:
|
|
description: A list of eHoldings titles
|
|
schema:
|
|
items:
|
|
$ref: "../swagger.yaml#/definitions/erm_eholdings_title"
|
|
type: array
|
|
400:
|
|
description: Bad request
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
403:
|
|
description: Access forbidden
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
500:
|
|
description: |-
|
|
Internal server error. Possible `error_code` attribute values:
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
503:
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
erm: 1
|
|
post:
|
|
x-mojo-to: ERM::EHoldings::Titles#add
|
|
operationId: addErmEHoldingsTitles
|
|
tags:
|
|
- erm_eholdings_titles
|
|
summary: Add eholding
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- description: Provider name
|
|
in: path
|
|
name: provider
|
|
required: true
|
|
type: string
|
|
- description: A JSON object containing information about the new title
|
|
in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/erm_eholdings_title"
|
|
responses:
|
|
201:
|
|
description: A successfully created title
|
|
schema:
|
|
items:
|
|
$ref: "../swagger.yaml#/definitions/erm_eholdings_title"
|
|
400:
|
|
description: Bad parameter
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
401:
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
403:
|
|
description: Access forbidden
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
404:
|
|
description: Ressource not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
409:
|
|
description: Conflict in creating resource
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
500:
|
|
description: |-
|
|
Internal server error. Possible `error_code` attribute values:
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
503:
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
erm: 1
|
|
"/erm/eholdings/{provider}/titles/{title_id}":
|
|
get:
|
|
x-mojo-to: ERM::EHoldings::Titles#get
|
|
operationId: getErmEHoldingsTitles
|
|
tags:
|
|
- erm_eholdings_titles
|
|
summary: Get titles
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- description: Provider name
|
|
in: path
|
|
name: provider
|
|
required: true
|
|
type: string
|
|
- $ref: "../swagger.yaml#/parameters/eholdings_title_id_pp"
|
|
- name: x-koha-embed
|
|
in: header
|
|
required: false
|
|
description: Embed list sent as a request header
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum:
|
|
- resources
|
|
- resources.package
|
|
collectionFormat: csv
|
|
responses:
|
|
200:
|
|
description: An eHolding title
|
|
schema:
|
|
items:
|
|
$ref: "../swagger.yaml#/definitions/erm_eholdings_title"
|
|
401:
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
403:
|
|
description: Access forbidden
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
404:
|
|
description: Ressource not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
500:
|
|
description: |-
|
|
Internal server error. Possible `error_code` attribute values:
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
503:
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
erm: 1
|
|
put:
|
|
x-mojo-to: ERM::EHoldings::Titles#update
|
|
operationId: updateErmEHoldingsTitles
|
|
tags:
|
|
- erm_eholdings_titles
|
|
summary: Update titles
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- description: Provider name
|
|
in: path
|
|
name: provider
|
|
required: true
|
|
type: string
|
|
- $ref: "../swagger.yaml#/parameters/eholdings_title_id_pp"
|
|
- name: body
|
|
in: body
|
|
description: A JSON object containing new information about existing title
|
|
required: true
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/erm_eholdings_title"
|
|
- name: x-koha-embed
|
|
in: header
|
|
required: false
|
|
description: Embed list sent as a request header
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum:
|
|
- resources
|
|
- resources.package
|
|
collectionFormat: csv
|
|
responses:
|
|
200:
|
|
description: A successfully updated title
|
|
schema:
|
|
items:
|
|
$ref: "../swagger.yaml#/definitions/erm_eholdings_title"
|
|
400:
|
|
description: Bad parameter
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
403:
|
|
description: Access forbidden
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
404:
|
|
description: Ressource not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
409:
|
|
description: Conflict in updating resource
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
500:
|
|
description: |-
|
|
Internal server error. Possible `error_code` attribute values:
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
503:
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
erm: 1
|
|
delete:
|
|
x-mojo-to: ERM::EHoldings::Titles#delete
|
|
operationId: deleteErmEHoldingsTitles
|
|
tags:
|
|
- erm_eholdings_titles
|
|
summary: Delete eHolding title
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- description: Provider name
|
|
in: path
|
|
name: provider
|
|
required: true
|
|
type: string
|
|
- $ref: "../swagger.yaml#/parameters/eholdings_title_id_pp"
|
|
responses:
|
|
204:
|
|
description: title deleted
|
|
400:
|
|
description: title deletion failed
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
401:
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
403:
|
|
description: Access forbidden
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
404:
|
|
description: Ressource not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
409:
|
|
description: Conflict in deleting resource
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
500:
|
|
description: |-
|
|
Internal server error. Possible `error_code` attribute values:
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
503:
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
erm: 1
|
|
/erm/eholdings/local/titles/import:
|
|
post:
|
|
x-mojo-to: ERM::EHoldings::Titles#import_from_list
|
|
operationId: importErmEHoldingsTitles
|
|
tags:
|
|
- erm_eholdings_titles
|
|
summary: Import local titles
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
parameters:
|
|
- description: The list_id of the list to import
|
|
in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list_id:
|
|
type: string
|
|
package_id:
|
|
type: string
|
|
additionalProperties: false
|
|
responses:
|
|
201:
|
|
description: Successfully enqueued the import job
|
|
schema:
|
|
type: object
|
|
properties:
|
|
job_id:
|
|
type: string
|
|
additionalProperties: false
|
|
400:
|
|
description: Bad parameter
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
401:
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
403:
|
|
description: Access forbidden
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
404:
|
|
description: Ressource not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
409:
|
|
description: Conflict in creating resource
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
500:
|
|
description: |-
|
|
Internal server error. Possible `error_code` attribute values:
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
503:
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
erm: 1
|