Bug 17428: [REST] Cities swagger specification

This patch adds the swagger definitions for the /cities endpoint

Signed-off-by: Josef Moravec <josef.moravec@gmail.com>

Signed-off-by: Jonathan Druart <jonathan.druart@biblibre.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>

api/v1/swagger/definitions.json

@@ -1,4 +1,7 @@
 {
+  "city": {
+    "$ref": "definitions/city.json"
+  },
   "patron": {
     "$ref": "definitions/patron.json"
   },

api/v1/swagger/definitions/city.json

@@ -0,0 +1,24 @@
+{
+  "type": "object",
+  "properties": {
+      "cityid": {
+        "$ref": "../x-primitives.json#/cityid"
+      },
+      "city_name": {
+        "description": "city name",
+        "type": "string"
+      },
+      "city_state": {
+        "description": "city state",
+        "type": ["string", "null"]
+      },
+      "city_zipcode": {
+        "description": "city zipcode",
+        "type": ["string", "null"]
+      },
+      "city_country": {
+        "description": "city country",
+        "type": ["string", "null"]
+      }
+  }
+}

api/v1/swagger/parameters.json

@@ -5,6 +5,9 @@
   "borrowernumberQueryParam": {
     "$ref": "parameters/patron.json#/borrowernumberQueryParam"
   },
+  "cityidPathParam": {
+    "$ref": "parameters/city.json#/cityidPathParam"
+  },
   "holdIdPathParam": {
     "$ref": "parameters/hold.json#/holdIdPathParam"
   }

api/v1/swagger/parameters/city.json

@@ -0,0 +1,9 @@
+{
+    "cityidPathParam": {
+      "name": "cityid",
+      "in": "path",
+      "description": "City id",
+      "required": true,
+      "type": "integer"
+    }
+}

api/v1/swagger/paths.json

@@ -1,4 +1,10 @@
 {
+  "/cities": {
+    "$ref": "paths/cities.json#/~1cities"
+  },
+  "/cities/{cityid}": {
+    "$ref": "paths/cities.json#/~1cities~1{cityid}"
+  },
   "/holds": {
     "$ref": "paths/holds.json#/~1holds"
   },

api/v1/swagger/paths/cities.json

@@ -0,0 +1,217 @@
+{
+  "/cities": {
+    "get": {
+      "x-mojo-controller": "Koha::REST::V1::Cities",
+      "operationId": "list",
+      "tags": ["cities"],
+      "produces": [
+        "application/json"
+      ],
+      "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"
+            }
+        }
+      }
+    },
+    "post": {
+      "x-mojo-controller": "Koha::REST::V1::Cities",
+      "operationId": "add",
+      "tags": ["cities"],
+      "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": {
+        "200": {
+          "description": "City added",
+          "schema": {
+            "$ref": "../definitions.json#/city"
+          }
+        },
+        "403": {
+          "description": "Access forbidden",
+          "schema": {
+            "$ref": "../definitions.json#/error"
+          }
+        },
+        "500": {
+            "description": "Internal error",
+            "schema": {
+                "$ref": "../definitions.json#/error"
+            }
+        }
+      },
+      "x-koha-authorization": {
+        "permissions": {
+          "parameters": "parameters_remaining_permissions"
+        }
+      }
+    }
+  },
+  "/cities/{cityid}": {
+    "get": {
+      "x-mojo-controller": "Koha::REST::V1::Cities",
+      "operationId": "get",
+      "tags": ["cities"],
+      "parameters": [
+        {
+          "$ref": "../parameters.json#/cityidPathParam"
+        }
+      ],
+      "produces": [
+        "application/json"
+      ],
+      "responses": {
+        "200": {
+          "description": "A city",
+          "schema": {
+            "$ref": "../definitions.json#/city"
+          }
+        },
+        "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"
+            }
+        }
+      }
+    },
+    "put": {
+      "x-mojo-controller": "Koha::REST::V1::Cities",
+      "operationId": "update",
+      "tags": ["cities"],
+      "parameters": [
+        {
+          "$ref": "../parameters.json#/cityidPathParam"
+        },
+        {
+          "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": {
+        "200": {
+          "description": "A city",
+          "schema": {
+            "$ref": "../definitions.json#/city"
+          }
+        },
+        "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"
+            }
+        }
+      },
+      "x-koha-authorization": {
+        "permissions": {
+          "parameters": "parameters_remaining_permissions"
+        }
+      }
+    },
+    "delete": {
+      "x-mojo-controller": "Koha::REST::V1::Cities",
+      "operationId": "delete",
+      "tags": ["cities"],
+      "parameters": [
+        {
+          "$ref": "../parameters.json#/cityidPathParam"
+        }
+      ],
+      "produces": [
+        "application/json"
+      ],
+      "responses": {
+        "200": {
+          "description": "City deleted",
+          "schema": {
+            "type": "string"
+          }
+        },
+        "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"
+            }
+        }
+      },
+      "x-koha-authorization": {
+        "permissions": {
+          "parameters": "parameters_remaining_permissions"
+        }
+      }
+    }
+  }
+}

api/v1/swagger/x-primitives.json

@@ -15,6 +15,10 @@
     "type": ["string", "null"],
     "description": "library assigned user identifier"
   },
+  "cityid": {
+    "type": "string",
+    "description": "internally assigned city identifier"
+  },
   "email": {
     "type": ["string", "null"],
     "description": "primary email address for patron's primary address"