From 20e45bbb9c9de677f3a30731aaab49f9b6588805 Mon Sep 17 00:00:00 2001
From: Tomas Cohen Arazi <tomascohen@theke.io>
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)