From e6e61bc320902e89d4fe5b3380f144435801a3e8 Mon Sep 17 00:00:00 2001 From: karen-hedges <133129444+karen-hedges@users.noreply.github.com> Date: Tue, 30 Sep 2025 17:08:34 +0100 Subject: [PATCH 1/9] DMP-5275 (Dev only) Spectral setup + initial warning reductions darts-api Added spectral config --- .spectral.yml | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 .spectral.yml diff --git a/.spectral.yml b/.spectral.yml new file mode 100644 index 0000000000..3383d1e503 --- /dev/null +++ b/.spectral.yml @@ -0,0 +1,98 @@ +extends: [ "spectral:oas" ] +rules: + 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 + + objects-should-forbid-unknown: + description: + Request objects should set additionalProperties: false + given: + - "$.paths.*.*.requestBody.content.*.schema" + then: + function: schema + functionOptions: + schema: + if: + properties: { type: { const: object } } + required: [ type ] + then: + required: [ additionalProperties ] + properties: { additionalProperties: { const: false } } + 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 From 0b96ec1fbf0a4faa4b5143c9af32f48ada34ad08 Mon Sep 17 00:00:00 2001 From: karen-hedges <133129444+karen-hedges@users.noreply.github.com> Date: Wed, 15 Oct 2025 13:42:06 +0100 Subject: [PATCH 2/9] DMP-5276-OpenapiValidator Added open apid validation --- .spectral.yml | 98 --------------------------------------------------- 1 file changed, 98 deletions(-) delete mode 100644 .spectral.yml diff --git a/.spectral.yml b/.spectral.yml deleted file mode 100644 index 3383d1e503..0000000000 --- a/.spectral.yml +++ /dev/null @@ -1,98 +0,0 @@ -extends: [ "spectral:oas" ] -rules: - 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 - - objects-should-forbid-unknown: - description: - Request objects should set additionalProperties: false - given: - - "$.paths.*.*.requestBody.content.*.schema" - then: - function: schema - functionOptions: - schema: - if: - properties: { type: { const: object } } - required: [ type ] - then: - required: [ additionalProperties ] - properties: { additionalProperties: { const: false } } - 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 From 24b5699ee91bd63b7ffd8a3d5d1d44116b753128 Mon Sep 17 00:00:00 2001 From: karen-hedges <133129444+karen-hedges@users.noreply.github.com> Date: Wed, 15 Oct 2025 13:44:34 +0100 Subject: [PATCH 3/9] DMP-5276-OpenapiValidator Added open apid validation --- .spectral.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.spectral.yaml b/.spectral.yaml index f95a3c8b63..4d3d4ad35e 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -81,4 +81,3 @@ rules: - required: [ format ] - required: [ pattern ] severity: warn - From f3da5761451b76bbab68222374c90b8b2a36669f Mon Sep 17 00:00:00 2001 From: karen-hedges <133129444+karen-hedges@users.noreply.github.com> Date: Wed, 15 Oct 2025 13:45:50 +0100 Subject: [PATCH 4/9] DMP-5276-OpenapiValidator Added open apid validation --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 504bac508d..603feb35dd 100644 --- a/README.md +++ b/README.md @@ -402,7 +402,7 @@ https://docs.stoplight.io/docs/spectral/b8391e051b7d8-installation To validate the OpenAPI specification: ```bash -spectral lint --verbose "src/main/resources/openapi/**/*.{yml,yaml}" +spectral lint "src/main/resources/openapi/**/*.{yml,yaml}" ``` Documentation: https://stoplight.io/open-source/spectral From 95552f8b1b0370c158f298c3e18c10f6951f6da4 Mon Sep 17 00:00:00 2001 From: karen-hedges <133129444+karen-hedges@users.noreply.github.com> Date: Wed, 15 Oct 2025 13:46:23 +0100 Subject: [PATCH 5/9] DMP-5276-OpenapiValidator Added open api validation --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 603feb35dd..504bac508d 100644 --- a/README.md +++ b/README.md @@ -402,7 +402,7 @@ https://docs.stoplight.io/docs/spectral/b8391e051b7d8-installation To validate the OpenAPI specification: ```bash -spectral lint "src/main/resources/openapi/**/*.{yml,yaml}" +spectral lint --verbose "src/main/resources/openapi/**/*.{yml,yaml}" ``` Documentation: https://stoplight.io/open-source/spectral From 723dbfbddf26e0ee8d4b11d7dee32a8db9aa40e4 Mon Sep 17 00:00:00 2001 From: karen-hedges <133129444+karen-hedges@users.noreply.github.com> Date: Fri, 10 Oct 2025 12:51:36 +0100 Subject: [PATCH 6/9] DMP-5276-OpenapiValidator Added open apid validation --- README.md | 13 ++++++++++++- lint-openapi-config.yaml | 5 +++++ 2 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 lint-openapi-config.yaml diff --git a/README.md b/README.md index 504bac508d..d0369aea27 100644 --- a/README.md +++ b/README.md @@ -399,7 +399,7 @@ This repository uses spectral to validate OpenAPI specifications. To install spe https://docs.stoplight.io/docs/spectral/b8391e051b7d8-installation -To validate the OpenAPI specification: +To validate the OpenAPI specification using spectral, run the following command from the root of the repository: ```bash spectral lint --verbose "src/main/resources/openapi/**/*.{yml,yaml}" @@ -407,6 +407,17 @@ spectral lint --verbose "src/main/resources/openapi/**/*.{yml,yaml}" Documentation: https://stoplight.io/open-source/spectral +## OpenAPI Validation + +The application uses OpenAPI validation to ensure that incoming requests and outgoing responses conform to the OpenAPI specification. +To enable OpenAPI validation, the following properties are set in the application configuration: + +```bash +lint-openapi -c lint-openapi-config.yaml "src/main/resources/openapi/**/*.yaml" +``` + +For more information on OpenAPI validation with IBM openapi validator, see the [openapi validator](https://github.com/IBM/openapi-validator). + Validate the data payload JSON Schemas: ### Supported labels diff --git a/lint-openapi-config.yaml b/lint-openapi-config.yaml new file mode 100644 index 0000000000..62875fc4ec --- /dev/null +++ b/lint-openapi-config.yaml @@ -0,0 +1,5 @@ +errorsOnly: false +limits: + warnings: 100 +outputFormat: 'json' +summaryOnly: true \ No newline at end of file From 95b773fec5083f113e872fa71f72e911dc23388f Mon Sep 17 00:00:00 2001 From: karen-hedges <133129444+karen-hedges@users.noreply.github.com> Date: Wed, 15 Oct 2025 13:50:26 +0100 Subject: [PATCH 7/9] DMP-5276-OpenapiValidator Added open api validation --- README.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index d0369aea27..06deaf4392 100644 --- a/README.md +++ b/README.md @@ -393,6 +393,13 @@ 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. +### Supported labels + +| Label | Usages | +|------------------------|--------------------------------------------------------------------------------------------------| +| enable_darts_portal | Deploys a DARTS portal instance alongside the API in the dev environment | +| enable_darts_fullstack | Not yet supported, but will deploy the full DARTS stack alongside the API in the dev environment | + ## OpenAPI Specification and Data Schema Validation This repository uses spectral to validate OpenAPI specifications. To install spectral, you can use npm or yarn: @@ -409,7 +416,11 @@ Documentation: https://stoplight.io/open-source/spectral ## OpenAPI Validation -The application uses OpenAPI validation to ensure that incoming requests and outgoing responses conform to the OpenAPI specification. +The application uses OpenAPI validation to ensure that incoming requests and outgoing responses conform to the OpenAPI specification. To install the IBM OpenAPI +validator, you can use npm or yarn: + +https://github.com/IBM/openapi-validator?tab=readme-ov-file#installation + To enable OpenAPI validation, the following properties are set in the application configuration: ```bash @@ -420,13 +431,6 @@ For more information on OpenAPI validation with IBM openapi validator, see the [ Validate the data payload JSON Schemas: -### Supported labels - -| Label | Usages | -|------------------------|--------------------------------------------------------------------------------------------------| -| enable_darts_portal | Deploys a DARTS portal instance alongside the API in the dev environment | -| enable_darts_fullstack | Not yet supported, but will deploy the full DARTS stack alongside the API in the dev environment | - ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details From d4b0ec6fa0ba4cdcfee77b0bf6cb75f0638a2895 Mon Sep 17 00:00:00 2001 From: karen-hedges <133129444+karen-hedges@users.noreply.github.com> Date: Wed, 15 Oct 2025 13:55:44 +0100 Subject: [PATCH 8/9] DMP-5276-OpenapiValidator Added open api validation --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 06deaf4392..aa36d93da3 100644 --- a/README.md +++ b/README.md @@ -424,7 +424,7 @@ https://github.com/IBM/openapi-validator?tab=readme-ov-file#installation To enable OpenAPI validation, the following properties are set in the application configuration: ```bash -lint-openapi -c lint-openapi-config.yaml "src/main/resources/openapi/**/*.yaml" +lint-openapi "src/main/resources/openapi/**/*.yaml" ``` For more information on OpenAPI validation with IBM openapi validator, see the [openapi validator](https://github.com/IBM/openapi-validator). From 7348afbbb44c663a65c1d9f3b5bd7f54b43d1504 Mon Sep 17 00:00:00 2001 From: karen-hedges <133129444+karen-hedges@users.noreply.github.com> Date: Thu, 30 Oct 2025 17:00:18 +0000 Subject: [PATCH 9/9] DMP-5276-OpenapiValidator Added open api validation --- README.md | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index aa36d93da3..3cf361e6fe 100644 --- a/README.md +++ b/README.md @@ -400,20 +400,6 @@ This repo contains overrides for the default dev environment configuration, cont | enable_darts_portal | Deploys a DARTS portal instance alongside the API in the dev environment | | enable_darts_fullstack | Not yet supported, but will deploy the full DARTS stack alongside the API in the dev environment | -## 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 using spectral, run the following command from the root of the repository: - -```bash -spectral lint --verbose "src/main/resources/openapi/**/*.{yml,yaml}" -``` - -Documentation: https://stoplight.io/open-source/spectral - ## OpenAPI Validation The application uses OpenAPI validation to ensure that incoming requests and outgoing responses conform to the OpenAPI specification. To install the IBM OpenAPI @@ -429,7 +415,11 @@ lint-openapi "src/main/resources/openapi/**/*.yaml" For more information on OpenAPI validation with IBM openapi validator, see the [openapi validator](https://github.com/IBM/openapi-validator). -Validate the data payload JSON Schemas: +This OpenAPI validation uses spectral ruleset to validate. To install spectral, you can use npm or yarn: + +https://docs.stoplight.io/docs/spectral/b8391e051b7d8-installation + +Documentation: https://stoplight.io/open-source/spectral ## License