DMP-5275 (Dev only) Spectral setup + initial warning reductions darts-api (#3087)

Author: karen-hedges

.spectral.yaml

@@ -0,0 +1,84 @@
+extends: [ "spectral:oas" ]
+rules:
+  oas3-valid-media-example: off
+  oas3-valid-schema-example: off
+  strings-need-bounds:
+    description: Strings must be bounded unless they already use format/enum/pattern
+    given:
+      - "$.components.schemas.*"
+      - "$.paths.*.*.parameters[*].schema"
+      - "$.paths.*.*.requestBody.content.*.schema"
+      - "$.paths.*.*.responses.*.content.*.schema"
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          if:
+            properties: { type: { const: string } }
+            required: [ type ]
+          then:
+            anyOf:
+              - required: [ maxLength ]
+              - required: [ enum ]
+              - required: [ pattern ]
+              - required: [ format ]
+    severity: warn
+
+  arrays-need-maxitems:
+    given:
+      - "$.components.schemas.*"
+      - "$.paths.*.*.parameters[*].schema"
+      - "$.paths.*.*.requestBody.content.*.schema"
+      - "$.paths.*.*.responses.*.content.*.schema"
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          if:
+            properties: { type: { const: array } }
+            required: [ type ]
+          then:
+            required: [ maxItems ]
+    severity: warn
+
+  path-string-params-need-format-or-pattern:
+    given:
+      - "$.paths.*.*.parameters[?(@.in=='path')].schema"
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          if:
+            properties: { type: { const: string } }
+            required: [ type ]
+          then:
+            anyOf:
+              - required: [ format ]
+              - required: [ pattern ]
+    severity: warn
+
+  param-id-needs-format-or-pattern:
+    given:
+      - "$.paths.*.*.parameters[?(@.name=='id')].schema"
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          anyOf:
+            - required: [ format ]
+            - required: [ pattern ]
+    severity: warn
+
+  schema-id-prop-needs-format-or-pattern:
+    given:
+      - "$.components.schemas.*.properties.id"
+      - "$.paths.*.*.requestBody.content.*.schema.properties.id"
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          anyOf:
+            - required: [ format ]
+            - required: [ pattern ]
+    severity: warn
+

README.md

@@ -328,12 +328,12 @@ There is no need to remove postgres and java or similar core images.
 The following Spring Profiles are defined. "External Components" are defined as any service upon which the application
 is dependent, such as database servers, web services etc.
 
-| Profile          | Config Location                                                | Purpose                                                                                        | External Components                                                                                                                                                                                                             |
-|------------------|----------------------------------------------------------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `local`          | `src/main/resources/application-local.yaml`                    | For running the application locally as a docker compose stack with `docker-compose-local.yml`. | Provided as needed by `docker-compose-local.yml`. No external connectivity permitted outside the network boundary of the stack.                                                                                                 |
+| Profile          | Config Location                                                | Purpose                                                                                        | External Components                                                                                                                                                                                                               |
+|------------------|----------------------------------------------------------------|------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `local`          | `src/main/resources/application-local.yaml`                    | For running the application locally as a docker compose stack with `docker-compose-local.yml`. | Provided as needed by `docker-compose-local.yml`. No external connectivity permitted outside the network boundary of the stack.                                                                                                   |
 | `intTest`        | `src/integrationTest/resources/application-intTest.yaml`       | For running integration tests under `src/integrationTest`.                                     | No interaction required or permitted, all external calls are mocked via embedded wiremock (for HTTP requests), an embedded database (for db queries) or `@MockitoBean` for anything else. Spring Security is explicitly disabled. |
-| `functionalTest` | `src/functionalTest/resources/application-functionalTest.yaml` | For running functional tests under `src/functionalTest`.                                       | Functional tests execute API calls against the application deployed in the PR environment. That application is deployed with the `dev` profile (see below).                                                                     |
-| `dev`            | `src/main/resources/application-dev.yaml`                      | For running the application in the Pull Request (dev) environment.                             | Interaction permitted with "real" components, which may be services deployed to a test environment.                                                                                                                             |
+| `functionalTest` | `src/functionalTest/resources/application-functionalTest.yaml` | For running functional tests under `src/functionalTest`.                                       | Functional tests execute API calls against the application deployed in the PR environment. That application is deployed with the `dev` profile (see below).                                                                       |
+| `dev`            | `src/main/resources/application-dev.yaml`                      | For running the application in the Pull Request (dev) environment.                             | Interaction permitted with "real" components, which may be services deployed to a test environment.                                                                                                                               |
 
 ## Automated Tasks
 
@@ -393,6 +393,22 @@ Please see the separate [Dev environment](https://tools.hmcts.net/confluence/dis
 
 This repo contains overrides for the default dev environment configuration, controlled by PR labels.
 
+## OpenAPI Specification and Data Schema Validation
+
+This repository uses spectral to validate OpenAPI specifications. To install spectral, you can use npm or yarn:
+
+https://docs.stoplight.io/docs/spectral/b8391e051b7d8-installation
+
+To validate the OpenAPI specification:
+
+```bash
+spectral lint --verbose "src/main/resources/openapi/**/*.{yml,yaml}"
+```
+
+Documentation: https://stoplight.io/open-source/spectral
+
+Validate the data payload JSON Schemas:
+
 ### Supported labels
 
 | Label                  | Usages                                                                                           |