gitea
/
Koha-clms
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Bug 29072: Move reference route /cities spec to YAML 

This patch moves the /cities routes spec and related files into YAML so
devs can use it as a reference for future routes.

To test:
1. Run:
   $ kshell
  k$ prove t/db_dependent/api/v1/cities.t
=> SUCCESS: Tests pass
2. Apply this patch
3. Repeat 1
=> SUCCESS: Tests still pass!
4. Sign off :-D

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>
This commit is contained in:
Tomas Cohen Arazi 2021-09-21 09:52:19 -03:00 committed by Jonathan Druart
parent 5e497a47a2
commit 4d3d400d7f
6 changed files with 242 additions and 361 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
api/v1/swagger/definitions.json
View File

@ -12,7 +12,7 @@
"$ref": "definitions/circ-rule-kind.json"
},
"city": {
"$ref": "definitions/city.json"
"$ref": "definitions/city.yaml"
},
"error": {
"$ref": "definitions/error.json"

26
api/v1/swagger/definitions/city.json
View File

@ -1,26 +0,0 @@
{
"type": "object",
"properties": {
"city_id": {
"$ref": "../x-primitives.json#/city_id"
},
"name": {
"description": "city name",
"type": "string"
},
"state": {
"description": "city state",
"type": ["string", "null"]
},
"postal_code": {
"description": "city postal code",
"type": ["string", "null"]
},
"country": {
"description": "city country",
"type": ["string", "null"]
}
},
"additionalProperties": false,
"required": ["name", "state", "postal_code", "country"]
}

29
api/v1/swagger/definitions/city.yaml Normal file
View File

@ -0,0 +1,29 @@
---
type: object
properties:
city_id:
$ref: ../x-primitives.json#/city_id
name:
description: city name
type: string
state:
description: city state
type:
- string
- "null"
postal_code:
description: city postal code
type:
- string
- "null"
country:
description: city country
type:
- string
- "null"
additionalProperties: false
required:
- name
- state
- postal_code
- country

4
api/v1/swagger/paths.json
View File

@ -45,10 +45,10 @@
"$ref": "paths/circulation-rules.json#/~1circulation-rules~1kinds"
},
"/cities": {
"$ref": "paths/cities.json#/~1cities"
"$ref": "paths/cities.yaml#/~1cities"
},
"/cities/{city_id}": {
"$ref": "paths/cities.json#/~1cities~1{city_id}"
"$ref": "paths/cities.yaml#/~1cities~1{city_id}"
},
"/clubs/{club_id}/holds": {
"$ref": "paths/clubs.json#/~1clubs~1{club_id}~1holds"

332
api/v1/swagger/paths/cities.json
View File

@ -1,332 +0,0 @@
{
"/cities": {
"get": {
"x-mojo-to": "Cities#list",
"operationId": "listCities",
"tags": [
"cities"
],
"summary": "List cities",
"produces": [
"application/json"
],
"parameters": [
{
"name": "name",
"in": "query",
"description": "Case insensative search on city name",
"required": false,
"type": "string"
},
{
"name": "state",
"in": "query",
"description": "Case insensative search on city state",
"required": false,
"type": "string"
},
{
"name": "country",
"in": "query",
"description": "Case insensative search on city country",
"required": false,
"type": "string"
},
{
"name": "postal_code",
"in": "query",
"description": "Case Insensative search on city postal code",
"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"
}
],
"responses": {
"200": {
"description": "A list of cities",
"schema": {
"type": "array",
"items": {
"$ref": "../definitions.json#/city"
}
}
},
"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": {
"catalogue": "1"
}
}
},
"post": {
"x-mojo-to": "Cities#add",
"operationId": "addCity",
"tags": [
"cities"
],
"summary": "Add city",
"parameters": [
{
"name": "body",
"in": "body",
"description": "A JSON object containing informations about the new hold",
"required": true,
"schema": {
"$ref": "../definitions.json#/city"
}
}
],
"produces": [
"application/json"
],
"responses": {
"201": {
"description": "City added",
"schema": {
"$ref": "../definitions.json#/city"
}
},
"401": {
"description": "Authentication required",
"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": {
"parameters": "manage_cities"
}
}
}
},
"/cities/{city_id}": {
"get": {
"x-mojo-to": "Cities#get",
"operationId": "getCity",
"tags": [
"cities"
],
"summary": "Get city",
"parameters": [
{
"$ref": "../parameters.json#/city_id_pp"
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "A city",
"schema": {
"$ref": "../definitions.json#/city"
}
},
"404": {
"description": "City 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": {
"catalogue": "1"
}
}
},
"put": {
"x-mojo-to": "Cities#update",
"operationId": "updateCity",
"tags": [
"cities"
],
"summary": "Update city",
"parameters": [
{
"$ref": "../parameters.json#/city_id_pp"
},
{
"name": "body",
"in": "body",
"description": "A city object",
"required": true,
"schema": {
"$ref": "../definitions.json#/city"
}
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "A city",
"schema": {
"$ref": "../definitions.json#/city"
}
},
"401": {
"description": "Authentication required",
"schema": {
"$ref": "../definitions.json#/error"
}
},
"403": {
"description": "Access forbidden",
"schema": {
"$ref": "../definitions.json#/error"
}
},
"404": {
"description": "City 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": {
"parameters": "manage_cities"
}
}
},
"delete": {
"x-mojo-to": "Cities#delete",
"operationId": "deleteCity",
"tags": [
"cities"
],
"summary": "Delete city",
"parameters": [
{
"$ref": "../parameters.json#/city_id_pp"
}
],
"produces": [
"application/json"
],
"responses": {
"204": {
"description": "City deleted"
},
"401": {
"description": "Authentication required",
"schema": {
"$ref": "../definitions.json#/error"
}
},
"403": {
"description": "Access forbidden",
"schema": {
"$ref": "../definitions.json#/error"
}
},
"404": {
"description": "City 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": {
"parameters": "manage_cities"
}
}
}
}
}

210
api/v1/swagger/paths/cities.yaml Normal file
View File

@ -0,0 +1,210 @@
---
/cities:
get:
x-mojo-to: Cities#list
operationId: listCities
tags:
- cities
summary: List cities
produces:
- application/json
parameters:
- name: name
in: query
description: Case insensative search on city name
required: false
type: string
- name: state
in: query
description: Case insensative search on city state
required: false
type: string
- name: country
in: query
description: Case insensative search on city country
required: false
type: string
- name: postal_code
in: query
description: Case Insensative search on city postal code
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
responses:
"200":
description: A list of cities
schema:
type: array
items:
$ref: ../definitions.json#/city
"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:
catalogue: "1"
post:
x-mojo-to: Cities#add
operationId: addCity
tags:
- cities
summary: Add city
parameters:
- name: body
in: body
description: A JSON object containing informations about the new hold
required: true
schema:
$ref: ../definitions.json#/city
produces:
- application/json
responses:
"201":
description: City added
schema:
$ref: ../definitions.json#/city
"401":
description: Authentication required
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:
parameters: manage_cities
"/cities/{city_id}":
get:
x-mojo-to: Cities#get
operationId: getCity
tags:
- cities
summary: Get city
parameters:
- $ref: ../parameters.json#/city_id_pp
produces:
- application/json
responses:
"200":
description: A city
schema:
$ref: ../definitions.json#/city
"404":
description: City 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:
catalogue: "1"
put:
x-mojo-to: Cities#update
operationId: updateCity
tags:
- cities
summary: Update city
parameters:
- $ref: ../parameters.json#/city_id_pp
- name: body
in: body
description: A city object
required: true
schema:
$ref: ../definitions.json#/city
produces:
- application/json
responses:
"200":
description: A city
schema:
$ref: ../definitions.json#/city
"401":
description: Authentication required
schema:
$ref: ../definitions.json#/error
"403":
description: Access forbidden
schema:
$ref: ../definitions.json#/error
"404":
description: City 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:
parameters: manage_cities
delete:
x-mojo-to: Cities#delete
operationId: deleteCity
tags:
- cities
summary: Delete city
parameters:
- $ref: ../parameters.json#/city_id_pp
produces:
- application/json
responses:
"204":
description: City deleted
"401":
description: Authentication required
schema:
$ref: ../definitions.json#/error
"403":
description: Access forbidden
schema:
$ref: ../definitions.json#/error
"404":
description: City 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:
parameters: manage_cities