fix(OpenAPI): Update spec

- Update redocly
- Disambiguate Scottish Postcode

Author: cblanc

.redocly.yaml

@@ -1,41 +1,24 @@
-apiDefinitions:
-# a set of named keys and values of entrypoints to OpenAPI 3 definitions.
-# example
-  idealpostcodes: ./openapi/openapi.yaml
-
-registry:
-# the API registry options
-
-# future products may be configured by extending this file
-
-
-lint:
-  extends:
-    - recommended
-  rules:
-    no-unused-components: warning
-referenceDocs:
-  htmlTemplate: ./openapi/index.html
-  theme:
-    sidebar:
-      textColor: '#d5dae6'
-      activeBgColor: '#07489e'
-      backgroundColor: '#05326d'
-      activeTextColor: '#FFFFFF'
-    typography:
-      code:
-        fontFamily: 'Fira Code, monospace'
-        fontSize: '13px'
-        backgroundColor: "rgba(38, 50, 56, 0.05)"
-        color: "#e53935"
-      headings:
-        fontFamily: 'Lato, sans-serif'
-      fontFamily: 'Lato, sans-serif'
-    colors:
-      primary:
-        main: "#32329f"
-  # generateCodeSamples:
-    # languages:  # Array of language config objects; indicates in which languages to generate code samples.
-    #   - lang: curl # Can be one of the following supported languages: "curl", "Node.js", "JavaScript".
-    #   - lang: "Node.js"
-    #   - lang: "JavaScript"
+apis:
+  idealpostcodes:
+    root: ./openapi/openapi.yaml
+theme:
+  openapi:
+    htmlTemplate: ./openapi/index.html
+    theme:
+      sidebar:
+        textColor: "#d5dae6"
+        activeBgColor: "#07489e"
+        backgroundColor: "#05326d"
+        activeTextColor: "#FFFFFF"
+      typography:
+        code:
+          fontFamily: "Fira Code, monospace"
+          fontSize: "13px"
+          backgroundColor: "rgba(38, 50, 56, 0.05)"
+          color: "#e53935"
+        headings:
+          fontFamily: "Lato, sans-serif"
+        fontFamily: "Lato, sans-serif"
+      colors:
+        primary:
+          main: "#32329f"

…ponents/responses/ScottishPostcodes.yaml …responses/ScottishPostcodesResponse.yamlopenapi/components/responses/ScottishPostcodes.yaml renamed to openapi/components/responses/ScottishPostcodesResponse.yaml openapi/components/responses/ScottishPostcodes.yaml renamed to openapi/components/responses/ScottishPostcodesResponse.yaml

@@ -13,5 +13,5 @@ properties:
     type: array
     items:
       oneOf:
-        - $ref: '../schemas/ScottishPostcodes.yaml'
-    description: 'Data for a given postcode'
+        - $ref: "../schemas/ScottishPostcodes.yaml"
+    description: "Data for a given postcode"

openapi/openapi.yaml

@@ -6,15 +6,15 @@ info:
     url: "https://opensource.org/licenses/MIT"
   title: API Reference - Postcodes.io
   termsOfService: "https://postcodes.io/about"
-  description: 
-    $ref: './description.md'
+  description:
+    $ref: "./description.md"
   contact:
     email: support@ideal-postcodes.co.uk
     name: Support
     url: https://ideal-postcodes.co.uk/support
 externalDocs:
   description: More on our APIs, libraries with guides and examples
-  url: 'https://docs.ideal-postcodes.co.uk/postcodesio'
+  url: "https://docs.ideal-postcodes.co.uk/postcodesio"
 servers:
   - url: "https://api.postcodes.io"
     description: "API Server"
@@ -33,34 +33,34 @@ tags:
 x-tagGroups:
   - name: API
     tags:
-    - Postcode Lookup
-    - Postcode Query
-    - Nearest Postcode
-    - Random Postcode
-    - Terminated Postcodes
-    - Scottish Postcodes
-    - Outward Code Lookup
-    - Place Search
-    - Place Query
-    - Random Place
+      - Postcode Lookup
+      - Postcode Query
+      - Nearest Postcode
+      - Random Postcode
+      - Terminated Postcodes
+      - Scottish Postcodes
+      - Outward Code Lookup
+      - Place Search
+      - Place Query
+      - Random Place
 paths:
-  '/postcodes/{postcode}':
-    $ref: 'paths/postcodes@{postcode}.yaml'
-  '/postcodes':
-    $ref: 'paths/postcodes.yaml'
-  '/postcodes/{postcode}/nearest':
-    $ref: 'paths/postcodes@{postcode}@nearest.yaml'
-  '/random/postcodes':
-    $ref: 'paths/random@postcodes.yaml'
-  '/terminated_postcodes/{postcode}':
-    $ref: 'paths/terminated_postcodes@{postcode}.yaml'
-  '/scotland/postcodes/{postcode}':
-    $ref: 'paths/scotland@postcodes@{postcode}.yaml'
-  '/outcodes/{outcode}':
-    $ref: 'paths/outcodes@{outcode}.yaml'
-  '/places/{code}':
-    $ref: 'paths/places@{code}.yaml'
-  '/places':
-    $ref: 'paths/places.yaml'
-  '/random/places':
-    $ref: 'paths/random@places.yaml'
+  "/postcodes/{postcode}":
+    $ref: "paths/postcodes@{postcode}.yaml"
+  "/postcodes":
+    $ref: "paths/postcodes.yaml"
+  "/postcodes/{postcode}/nearest":
+    $ref: "paths/postcodes@{postcode}@nearest.yaml"
+  "/random/postcodes":
+    $ref: "paths/random@postcodes.yaml"
+  "/terminated_postcodes/{postcode}":
+    $ref: "paths/terminated_postcodes@{postcode}.yaml"
+  "/scotland/postcodes/{postcode}":
+    $ref: "paths/scotland@postcodes@{postcode}.yaml"
+  "/outcodes/{outcode}":
+    $ref: "paths/outcodes@{outcode}.yaml"
+  "/places/{code}":
+    $ref: "paths/places@{code}.yaml"
+  "/places":
+    $ref: "paths/places.yaml"
+  "/random/places":
+    $ref: "paths/random@places.yaml"

openapi/paths/scotland@postcodes@{postcode}.yaml

@@ -15,19 +15,19 @@ get:
       schema:
         type: string
   responses:
-    '200':
+    "200":
       description: Success
       content:
         application/json:
           schema:
-            $ref: '../components/responses/ScottishPostcodes.yaml'
+            $ref: "../components/responses/ScottishPostcodesResponse.yaml"
   x-codeSamples:
-  - lang: 'http'
-    label: 'URL'
-    source: |
-      https://api.postcodes.io/scotland/postcodes/IV27JB
-  - lang: 'cURL'
-    label: 'CLI'
-    source: |
-      curl -G -k \
-      --url 'https://api.postcodes.io/scotland/postcodes/IV27JB'
+    - lang: "http"
+      label: "URL"
+      source: |
+        https://api.postcodes.io/scotland/postcodes/IV27JB
+    - lang: "cURL"
+      label: "CLI"
+      source: |
+        curl -G -k \
+        --url 'https://api.postcodes.io/scotland/postcodes/IV27JB'