From 1153716e55d330ad02c2ca358bec8f93af3c09e5 Mon Sep 17 00:00:00 2001
From: Tomas Cohen Arazi <tomascohen@theke.io>
Date: Tue, 21 Sep 2021 09:52:19 -0300
Subject: [PATCH] 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>
---
 api/v1/swagger/definitions.json      |   2 +-
 api/v1/swagger/definitions/city.json |  26 ---
 api/v1/swagger/definitions/city.yaml |  29 +++
 api/v1/swagger/paths.json            |   4 +-
 api/v1/swagger/paths/cities.json     | 332 ---------------------------
 api/v1/swagger/paths/cities.yaml     | 210 +++++++++++++++++
 6 files changed, 242 insertions(+), 361 deletions(-)
 delete mode 100644 api/v1/swagger/definitions/city.json
 create mode 100644 api/v1/swagger/definitions/city.yaml
 delete mode 100644 api/v1/swagger/paths/cities.json
 create mode 100644 api/v1/swagger/paths/cities.yaml

diff --git a/api/v1/swagger/definitions.json b/api/v1/swagger/definitions.json
index 02dbc95c019..402eed6b256 100644
--- a/api/v1/swagger/definitions.json
+++ b/api/v1/swagger/definitions.json
@@ -12,7 +12,7 @@
     "$ref": "definitions/circ-rule-kind.json"
   },
   "city": {
-    "$ref": "definitions/city.json"
+    "$ref": "definitions/city.yaml"
   },
   "error": {
     "$ref": "definitions/error.json"
diff --git a/api/v1/swagger/definitions/city.json b/api/v1/swagger/definitions/city.json
deleted file mode 100644
index 8643e98c145..00000000000
--- a/api/v1/swagger/definitions/city.json
+++ /dev/null
@@ -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"]
-}
diff --git a/api/v1/swagger/definitions/city.yaml b/api/v1/swagger/definitions/city.yaml
new file mode 100644
index 00000000000..b744e140c33
--- /dev/null
+++ b/api/v1/swagger/definitions/city.yaml
@@ -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
diff --git a/api/v1/swagger/paths.json b/api/v1/swagger/paths.json
index cdcd0368c52..23f420cc05f 100644
--- a/api/v1/swagger/paths.json
+++ b/api/v1/swagger/paths.json
@@ -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"
diff --git a/api/v1/swagger/paths/cities.json b/api/v1/swagger/paths/cities.json
deleted file mode 100644
index d5338460011..00000000000
--- a/api/v1/swagger/paths/cities.json
+++ /dev/null
@@ -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"
-        }
-      }
-    }
-  }
-}
diff --git a/api/v1/swagger/paths/cities.yaml b/api/v1/swagger/paths/cities.yaml
new file mode 100644
index 00000000000..88c87f6a6db
--- /dev/null
+++ b/api/v1/swagger/paths/cities.yaml
@@ -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
-- 
2.20.1