From 20e45bbb9c9de677f3a30731aaab49f9b6588805 Mon Sep 17 00:00:00 2001 From: Tomas Cohen Arazi Date: Mon, 3 Feb 2020 15:26:40 -0300 Subject: [PATCH] Bug 24857: API spec --- api/v1/swagger/definitions.json | 3 + api/v1/swagger/definitions/volume.json | 48 ++ api/v1/swagger/paths.json | 18 +- api/v1/swagger/paths/biblios_volumes.json | 593 ++++++++++++++++++++++ 4 files changed, 659 insertions(+), 3 deletions(-) create mode 100644 api/v1/swagger/definitions/volume.json create mode 100644 api/v1/swagger/paths/biblios_volumes.json diff --git a/api/v1/swagger/definitions.json b/api/v1/swagger/definitions.json index a27fa0de22..caaf880ee0 100644 --- a/api/v1/swagger/definitions.json +++ b/api/v1/swagger/definitions.json @@ -56,6 +56,9 @@ "vendor": { "$ref": "definitions/vendor.json" }, + "volume": { + "$ref": "definitions/volume.json" + }, "return_claim": { "$ref": "definitions/return_claim.json" } diff --git a/api/v1/swagger/definitions/volume.json b/api/v1/swagger/definitions/volume.json new file mode 100644 index 0000000000..33559948f3 --- /dev/null +++ b/api/v1/swagger/definitions/volume.json @@ -0,0 +1,48 @@ +{ + "type": "object", + "properties": { + "volume_id": { + "type": "integer", + "readOnly": true, + "description": "Internal identifier for the volume" + }, + "biblio_id": { + "type": "integer", + "readOnly": true, + "description": "Internal identifier for the parent bibliographic record" + }, + "description": { + "type": "string", + "description": "Volume description" + }, + "display_order": { + "type": "integer", + "description": "Volume description" + }, + "creation_date": { + "type": "string", + "format": "date-time", + "readOnly": true, + "description": "Date and time the volume was created" + }, + "modification_date": { + "type": "string", + "format": "date-time", + "readOnly": true, + "description": "Date and time the volume was last modified" + }, + "items": { + "type": [ + "integer", + "null" + ], + "readOnly": true, + "description": "A list of items that belong to the volume (x-koha-embed)" + } + }, + "additionalProperties": false, + "required": [ + "volume_id", + "biblio_id" + ] +} diff --git a/api/v1/swagger/paths.json b/api/v1/swagger/paths.json index ed9ed0627c..fa826f6a80 100644 --- a/api/v1/swagger/paths.json +++ b/api/v1/swagger/paths.json @@ -17,6 +17,21 @@ "/acquisitions/funds": { "$ref": "paths/acquisitions_funds.json#/~1acquisitions~1funds" }, + "/biblios/{biblio_id}": { + "$ref": "paths/biblios.json#/~1biblios~1{biblio_id}" + }, + "/biblios/{biblio_id}/volumes": { + "$ref": "paths/biblios_volumes.json#/~1biblios~1{biblio_id}~1volumes" + }, + "/biblios/{biblio_id}/volumes/{volume_id}": { + "$ref": "paths/biblios_volumes.json#/~1biblios~1{biblio_id}~1volumes~1{volume_id}" + }, + "/biblios/{biblio_id}/volumes/{volume_id}/items": { + "$ref": "paths/biblios_volumes.json#/~1biblios~1{biblio_id}~1volumes~1{volume_id}~1items" + }, + "/biblios/{biblio_id}/volumes/{volume_id}/items/{item_id}": { + "$ref": "paths/biblios_volumes.json#/~1biblios~1{biblio_id}~1volumes~1{volume_id}~1items~1{item_id}" + }, "/checkouts": { "$ref": "paths/checkouts.json#/~1checkouts" }, @@ -35,9 +50,6 @@ "/cities/{city_id}": { "$ref": "paths/cities.json#/~1cities~1{city_id}" }, - "/biblios/{biblio_id}": { - "$ref": "paths/biblios.json#/~1biblios~1{biblio_id}" - }, "/clubs/{club_id}/holds": { "$ref": "paths/clubs.json#/~1clubs~1{club_id}~1holds" }, diff --git a/api/v1/swagger/paths/biblios_volumes.json b/api/v1/swagger/paths/biblios_volumes.json new file mode 100644 index 0000000000..2d2ef7a69e --- /dev/null +++ b/api/v1/swagger/paths/biblios_volumes.json @@ -0,0 +1,593 @@ +{ + "/biblios/{biblio_id}/volumes": { + "get": { + "x-mojo-to": "Biblios::Volumes#list", + "operationId": "listVolumes", + "tags": [ + "volumes" + ], + "parameters": [ + { + "name": "biblio_id", + "in": "path", + "description": "Internal identifier for the parent bibliographic record", + "required": true, + "type": "string" + }, + { + "$ref": "../parameters.json#/match" + }, + { + "$ref": "../parameters.json#/order_by" + }, + { + "$ref": "../parameters.json#/page" + }, + { + "$ref": "../parameters.json#/per_page" + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "A list of volumes", + "schema": { + "type": "array", + "items": { + "$ref": "../definitions.json#/volume" + } + } + }, + "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" + } + }, + "x-koha-embed": [ + "items" + ] + }, + "post": { + "x-mojo-to": "Biblios::Volumes#add", + "operationId": "addVolume", + "tags": [ + "volumes" + ], + "parameters": [ + { + "name": "biblio_id", + "in": "path", + "description": "Internal identifier for the parent bibliographic record", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "description": "A JSON object representing a volume", + "required": true, + "schema": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "Volume description" + }, + "display_order": { + "type": "integer", + "description": "Position in waiting queue" + } + } + } + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "A successfully created volume", + "schema": { + "$ref": "../definitions.json#/volume" + } + }, + "400": { + "description": "Bad parameter", + "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": "Resource not found", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "409": { + "description": "Conflict in creating resource", + "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" + } + } + } + }, + "/biblios/{biblio_id}/volumes/{volume_id}": { + "get": { + "x-mojo-to": "Biblios::Volumes#get", + "operationId": "getVolume", + "tags": [ + "volumes" + ], + "parameters": [ + { + "name": "biblio_id", + "in": "path", + "description": "Internal identifier for the parent bibliographic record", + "required": true, + "type": "string" + }, + { + "name": "volume_id", + "in": "path", + "description": "Internal identifier for the volume", + "required": true, + "type": "string" + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "A volume", + "schema": { + "$ref": "../definitions.json#/volume" + } + }, + "400": { + "description": "Missing or wrong parameters", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Volume 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-embed": [ + "items" + ], + "x-koha-authorization": { + "permissions": { + "catalogue": "1" + } + } + }, + "put": { + "x-mojo-to": "Biblios::Volumes#update", + "operationId": "updateVolume", + "tags": [ + "volumes" + ], + "parameters": [ + { + "name": "biblio_id", + "in": "path", + "description": "Internal identifier for the parent bibliographic record", + "required": true, + "type": "string" + }, + { + "name": "volume_id", + "in": "path", + "description": "Internal identifier for the volume", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "description": "A JSON object with the new values for the volume", + "required": true, + "schema": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "Volume description" + }, + "display_order": { + "type": "integer", + "description": "Position in waiting queue" + } + } + } + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "The updated volume", + "schema": { + "$ref": "../definitions.json#/volume" + } + }, + "400": { + "description": "Bad request", + "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": "Volume 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" + } + }, + "x-koha-embed": [ + "items" + ] + }, + "delete": { + "x-mojo-to": "Biblios::Volumes#delete", + "operationId": "deleteVolume", + "tags": [ + "volumes" + ], + "parameters": [ + { + "name": "biblio_id", + "in": "path", + "description": "Internal identifier for the parent bibliographic record", + "required": true, + "type": "string" + }, + { + "name": "volume_id", + "in": "path", + "description": "Internal identifier for the volume", + "required": true, + "type": "string" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "204": { + "description": "Volume deleted", + "schema": { + "type": "string" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Volume 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" + } + } + } + }, + "/biblios/{biblio_id}/volumes/{volume_id}/items": { + "post": { + "x-mojo-to": "Biblios::Volumes::Items#add", + "operationId": "addVolumeItem", + "tags": [ + "volumes" + ], + "parameters": [ + { + "name": "biblio_id", + "in": "path", + "description": "Internal identifier for the parent bibliographic record", + "required": true, + "type": "string" + }, + { + "name": "volume_id", + "in": "path", + "description": "Internal identifier for the volume", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "description": "A JSON object containing an item_id", + "required": true, + "schema": { + "type": "object", + "properties": { + "item_id": { + "type": "integer", + "description": "Internal identifier for an item to be linked" + } + } + } + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "Item linked to volume" + }, + "400": { + "description": "Bad request", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "409": { + "description": "Request conflicts", + "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" + } + }, + "x-koha-embed": [ + "items" + ] + } + }, + "/biblios/{biblio_id}/volumes/{volume_id}/items/{item_id}": { + "delete": { + "x-mojo-to": "Biblios::Volumes::Items#delete", + "operationId": "deleteVolumeItems", + "tags": [ + "volumes" + ], + "parameters": [ + { + "name": "biblio_id", + "in": "path", + "description": "Internal identifier for the parent bibliographic record", + "required": true, + "type": "string" + }, + { + "name": "volume_id", + "in": "path", + "description": "Internal identifier for the volume", + "required": true, + "type": "string" + }, + { + "name": "item_id", + "in": "path", + "description": "Internal identifier for the item", + "required": true, + "type": "string" + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "204": { + "description": "Item unlinked from volume", + "schema": { + "type": "string" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Item not linked to volume", + "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" + } + } + } + } +} -- 2.21.1 (Apple Git-122.3)