added linting rules for root path and api info schema, plus other

smaller updates.

Author: milkshakeuk

.github/workflows/lint-example-oas.yml

@@ -20,11 +20,21 @@ jobs:
     name: Lint Example OpenAPI
 
     runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      issues: read
+      checks: write
+      pull-requests: write
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      # Run Spectral
-      - uses: stoplightio/spectral-action@latest
-        with:
-          file_glob: "./example/*.{json,yml,yaml}"
+      - name: Install spectral
+        run: curl -L https://raw.github.com/stoplightio/spectral/master/scripts/install.sh | sh
+
+      - name: Lint example OpenAPI
+        run: |
+          spectral --version
+          spectral lint "./example/*.{json,yml,yaml}" -f github-actions

docs/api-design-guidelines/pagination-filtering-sorting.md

@@ -76,8 +76,7 @@ paths:
           description: The type of test to filter by.
           schema:
             type: string
-            examples:
-            - Lateral Flow Test
+            example: Lateral Flow Test
         - in: query
           name: result
           required: false
@@ -88,10 +87,7 @@ paths:
               - POSITIVE
               - NEGATIVE
               - UNREADABLE
-            examples:
-              - POSITIVE
-              - NEGATIVE
-              - UNREADABLE
+            example: POSITIVE
 ```
 
 ### Alternative Example
@@ -119,18 +115,14 @@ paths:
             type: string
             pattern: '^\d{3}(?:-| )?\d{3}(?:-| )?\d{4}$'
             description: The nhs number of patient
-            examples:
-              - '4857773456'
-              - '485 777 3456'
-              - '485-777-3456'
+            example: '4857773456'
         - in: query
           name: type
           required: false
           description: The type of test to filter by.
           schema:
             type: string
-            examples:
-            - Lateral Flow Test
+            example: Lateral Flow Test
         - in: query
           name: result
           required: false
@@ -141,10 +133,7 @@ paths:
               - POSITIVE
               - NEGATIVE
               - UNREADABLE
-            examples:
-              - POSITIVE
-              - NEGATIVE
-              - UNREADABLE
+            example: POSITIVE
 ```
 
 ## Sorting
@@ -158,3 +147,22 @@ If a explicit sort order is desired, the query parameter `sort` **SHOULD** be us
 ``` text
 GET /product/v1/results?sort=nhsNumber|asc,type|desc
 ```
+
+``` yaml
+components:
+  parameters:
+    sortParam:
+      in: query
+      name: sort
+      description: How to sort the results.
+      schema:
+        type: string
+        pattern: ^[a-z]+(?:[A-Z][a-z]+)+\|(?:asc|desc)(?:,[a-z]+(?:[A-Z][a-z]+)*\|(?:asc|desc))*$
+      examples:
+        sortBySingleField:
+          value: nhsNumber|asc
+          summary: Sort by a single field
+        sortByMultipleField:
+          value: nhsNumber|asc,type|desc
+          summary: Sort by multiple fields
+```

docs/api-design-guidelines/versioning-and-deprecation.md

@@ -64,13 +64,15 @@ Avoid:
 
 `MINOR` and `PATCH` versions **MUST NOT** be added to the URI as they do not affect compatibility.
 
-There **SHOULD** be an endpoint to return version metadata that is also documented in the OpenAPI definition.
+## API root endpoint
+
+There **SHOULD** be an endpoint to return version metadata (typically the APIs root `/` endpoint) that is also documented in the OpenAPI definition, not only will this provide useful API metadata but will help API consumers know they're looking at the right place instead of getting a `404` or random `500` error as is common in some APIs.
 
 ``` text
 GET /namespace/product/v1
- 
+
 {
-  "name": "product",
+  "name": "Product API",
   "version": "1.0.1"
   "releaseDate": "2024-09-17"
   "documentation": "https://developer.ukhsa.gov.uk/namespace/product/v1/docs"

docs/spectral-rules/must/must-return-200-for-api-root.md

@@ -0,0 +1,27 @@
+# **MUST** return 200 for api root
+
+Root path **MUST** define a `200` response.
+
+## Valid Example
+
+``` yaml
+paths:
+  /:
+    get:
+      summary: Get API information.
+      description: Get API information.
+      operationId: getApiInfo
+      tags:
+        - API Meta Information
+      responses:
+        '200':
+          description: This response returns a information about the API.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiInfo'
+        default:
+          $ref: '#/components/responses/UnexpectedError'
+```
+
+[UKHSA Guidlelines Versioning](../../api-design-guidelines/versioning-and-deprecation.md#api-root-endpoint)

docs/spectral-rules/must/must-use-normalized-paths-without-empty-path-segments.md

@@ -5,13 +5,15 @@ Path segments **MUST** not contain duplicate slashes.
 ## Invalid Example
 
 ``` yaml
-/user//report:
+paths:
+  /user//report:
 ```
 
 ## Valid Example
 
 ``` yaml
-/beach-report:
+paths:
+  /user-report:
 ```
 
 [Zalando Guideline 136](https://opensource.zalando.com/restful-api-guidelines/#136)

docs/spectral-rules/must/must-use-normalized-paths-without-trailing-slash.md

@@ -0,0 +1,25 @@
+# **MUST** use normalised paths
+
+Path **MUST** start with a slash and **MUST NOT** end with a slash (except root path `/`).
+
+## Invalid Example
+
+``` yaml
+paths:
+  /patient/:
+    ...
+  /patient/{patientId}/results/:
+```
+
+## Valid Example
+
+``` yaml
+paths:
+  /:
+    ...
+  /patient:
+    ...
+  /patient/{patientId}/results:
+```
+
+[Zalando Guideline 136](https://opensource.zalando.com/restful-api-guidelines/#136)

docs/spectral-rules/must/must-use-normalized-paths.md

@@ -2,46 +2,42 @@
 
 `Problem` schema **MUST** include this set of minimal required properties and validations:
 
-``` yaml
-type: object
-properties:
-  type:
-    type: string
-    format: uri-reference
-  title:
-    type: string
-  status:
-    type: integer
-    format: int32
-  detail:
-    type: string
-  instance:
-    type: string
-```
-
 ## Valid Example
 
 ``` yaml
-title: Problem
-type: object
-properties:
-  type:
-    type: string
-    format: uri-reference
-    example: /my-example/user-error
-  title:
-    type: string
-    example: a title for the error situation
-  status:
-    type: integer
-    format: int32
-  detail:
-    type: string
-    example: description for the error situation
-  instance:
-    type: string
-    format: uri-reference
-    example:  /some/uri-reference#specific-occurrence-context
+ProblemDetails:
+  type: object
+  description: Schema for detailed problem information.
+  properties:
+    type:
+      type: string
+      description: A URI reference that identifies the problem type.
+      format: uri-reference
+      maxLength: 1024
+    status:
+      type: integer
+      description: The HTTP status code generated by the origin server for this occurrence of the problem.
+      format: int32
+      minimum: 100
+      maximum: 599
+    title:
+      type: string
+      description: A short, human-readable summary of the problem type. It should not change from occurrence to occurrence of the problem, except for purposes of localization.
+      maxLength: 1024
+    detail:
+      type: string
+      description: A human-readable explanation specific to this occurrence of the problem.
+      maxLength: 4096
+    instance:
+      type: string
+      description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
+      maxLength: 1024
+required:
+  - type
+  - status
+  - title
+  - detail
+  - instance
 ```
 
 [Zalando Guideline 176](https://opensource.zalando.com/restful-api-guidelines/#176)

docs/spectral-rules/must/must-use-valid-problem-json-schema.md

@@ -0,0 +1,45 @@
+# **MUST** use valid version info schema
+
+`ApiInfo` schema **MUST** include this set of minimal required properties and validations:
+
+## Valid Example
+
+``` yaml
+components:
+  schema:
+    ...
+    ApiInfo:
+      type: object
+      description: Schema for detailing API information.
+      properties:
+        name:
+          type: string
+          description: The name of the API.
+          example: Test Results API
+        version:
+          type: string
+          pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
+          description: The version of the API.
+          example: 1.0.0
+        releaseDate:
+          type: string
+          format: date
+          description: The release date of this API version.
+          example: 2025-02-26
+        documentation:
+          type: string
+          format: uri
+          description: A URL to the API documentation.
+          example: https://developer.ukhsa.gov.uk/namespace/product/v1/docs
+        releaseNotes:
+          type: string
+          format: uri
+          description: A URL to the API release notes.
+          example: https://developer.ukhsa.gov.uk/namespace/product/v1/releaseNotes
+      required:
+        - name
+        - version
+        - releaseDate
+        - documentation
+        - releaseNotes
+```

docs/spectral-rules/must/must-use-valid-version-info-schema.md

@@ -29,6 +29,6 @@ requestBody:
           type: string
 ```
 
-[UKHSA API Design](../../api-design-guidelines/api-design.md#response-format)
+[UKHSA Guidlines API Design](../../api-design-guidelines/api-design.md#response-format)
 
 [Zalando Guideline 210](https://opensource.zalando.com/restful-api-guidelines/#210)