From cdb9222a529c7d5a1a9252a95460a5a13ab9d689 Mon Sep 17 00:00:00 2001 From: dimaananskyi Date: Thu, 29 Aug 2024 18:45:35 +0300 Subject: [PATCH 01/23] chore: add arazzo rules documentation --- docs/rules/minimal.md | 1 + docs/rules/recommended.md | 2 + docs/rules/spot/parameters-not-in-body.md | 92 +++++++++++++++++++++++ docs/rules/spot/version-enum.md | 67 +++++++++++++++++ 4 files changed, 162 insertions(+) create mode 100644 docs/rules/spot/parameters-not-in-body.md create mode 100644 docs/rules/spot/version-enum.md diff --git a/docs/rules/minimal.md b/docs/rules/minimal.md index bbc49fddb..b3388733d 100644 --- a/docs/rules/minimal.md +++ b/docs/rules/minimal.md @@ -38,3 +38,4 @@ Warnings: - [security-defined](./security-defined.md) - [spec-components-invalid-map-name](./spec-components-invalid-map-name.md) - [tag-description](./tag-description.md) +- [version-enum](./spot/version-enum.md) diff --git a/docs/rules/recommended.md b/docs/rules/recommended.md index 8869d0ecb..90c2ecc3c 100644 --- a/docs/rules/recommended.md +++ b/docs/rules/recommended.md @@ -41,6 +41,8 @@ Warnings: - [operation-4xx-response](./operation-4xx-response.md) - [operation-operationId](./operation-operationId.md) - [tag-description](./tag-description.md) +- [version-enum](./spot/version-enum.md) +- [parameters-not-in-body](./spot/parameters-not-in-body.md) ## Recommended strict ruleset diff --git a/docs/rules/spot/parameters-not-in-body.md b/docs/rules/spot/parameters-not-in-body.md new file mode 100644 index 000000000..bbef25553 --- /dev/null +++ b/docs/rules/spot/parameters-not-in-body.md @@ -0,0 +1,92 @@ +--- +slug: /docs/cli/rules/spot/parameters-not-in-body +--- + +# parameters-not-in-body + +Requires the `in` section inside `parameters` must not contain a `body`. + +| ARAZZO | Compatibility | +|--------| ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> workflows --> workflow --> parameters + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +```mermaid +flowchart TD + +Root ==> x-parameters + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +```mermaid +flowchart TD + +Root ==> workflows --> workflow --> steps --> step --> parameters + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +This is `Spot` specific rule. +`body` is not supported in the `in` section inside `parameters`. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + parameters-not-in-body: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + parameters-not-in-body: error +``` + +Example of an **incorrect** license: + +```yaml Object example +workflows: + - workflowId: get-museum-hours + parameters: + - in: body + name: Authorization + value: Basic Og== +``` + +Example of a **correct** license: + +```yaml Object example +workflows: + - workflowId: get-museum-hours + parameters: + - in: header + name: Authorization + value: Basic Og== +``` + +## Related rules + +- [version-enum](./version-enum.md) + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/spot/parameters-not-in-body.ts) diff --git a/docs/rules/spot/version-enum.md b/docs/rules/spot/version-enum.md new file mode 100644 index 000000000..dd76a69a8 --- /dev/null +++ b/docs/rules/spot/version-enum.md @@ -0,0 +1,67 @@ +--- +slug: /docs/cli/rules/spot/version-enum +--- + +# version-enum + +Requires the `version` property must be one of the supported values. + +| ARAZZO | Compatibility | +|--------| ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> arazzo + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +This is `Spot` specific rule. +The `version` property must be one of the supported values witch is might be different to the `Arazzo` latest versions. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + version-enum: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + version-enum: error +``` + +Example of an **incorrect** license: + +```yaml Object example +arazzo: 1.0.1 +``` + +Example of a **correct** license: + +```yaml Object example +arazzo: 1.0.0 +``` + +## Related rules + +- [parameters-not-in-body](./parameters-not-in-body.md) + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/spot/version-enum.ts) + From c4de777a968a99fe4b2efd92674d7628092a42d1 Mon Sep 17 00:00:00 2001 From: dimaananskyi Date: Thu, 29 Aug 2024 19:01:01 +0300 Subject: [PATCH 02/23] chore: add arazzo rules documentation --- docs/rules/arazzo/parameters-unique.md | 95 +++++++++++++++++++++++ docs/rules/recommended.md | 1 + docs/rules/spot/parameters-not-in-body.md | 2 +- docs/rules/spot/version-enum.md | 5 +- 4 files changed, 99 insertions(+), 4 deletions(-) create mode 100644 docs/rules/arazzo/parameters-unique.md diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md new file mode 100644 index 000000000..391db8ee8 --- /dev/null +++ b/docs/rules/arazzo/parameters-unique.md @@ -0,0 +1,95 @@ +--- +slug: /docs/cli/rules/arazzo/parameters-unique +--- + +# parameters-unique + +Requires the `parameters` list not to include duplicate parameters. + +| ARAZZO | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> workflows --> workflow --> parameters + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +```mermaid +flowchart TD + +Root ==> x-parameters + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +```mermaid +flowchart TD + +Root ==> workflows --> workflow --> steps --> step --> parameters + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +A list of `parameters` that are applicable for step or all steps described under workflow should not be duplicated to avoid shallow parameter override. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + parameters-unique: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + parameters-unique: error +``` + +Example of an **incorrect** license: + +```yaml Object example +workflows: + - workflowId: get-museum-hours + parameters: + - in: header + name: Authorization + value: Main Og== + - in: header + name: Authorization + value: Basic Og== +``` + +Example of a **correct** license: + +```yaml Object example +workflows: + - workflowId: get-museum-hours + parameters: + - in: header + name: Authorization + value: Basic Og== + - in: header + name: Auth + value: Main Og== +``` + +## Related rules + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/parameters-unique.ts) diff --git a/docs/rules/recommended.md b/docs/rules/recommended.md index 90c2ecc3c..0d80fae9f 100644 --- a/docs/rules/recommended.md +++ b/docs/rules/recommended.md @@ -27,6 +27,7 @@ Errors: - [security-defined](./security-defined.md) - [spec-components-invalid-map-name](./spec-components-invalid-map-name.md) - [spec](./spec.md) +- [parameters-unique](./arazzo/parameters-unique.md) Warnings: diff --git a/docs/rules/spot/parameters-not-in-body.md b/docs/rules/spot/parameters-not-in-body.md index bbef25553..3e9a6d213 100644 --- a/docs/rules/spot/parameters-not-in-body.md +++ b/docs/rules/spot/parameters-not-in-body.md @@ -7,7 +7,7 @@ slug: /docs/cli/rules/spot/parameters-not-in-body Requires the `in` section inside `parameters` must not contain a `body`. | ARAZZO | Compatibility | -|--------| ------------- | +| ------ | ------------- | | 1.0.0 | ✅ | ```mermaid diff --git a/docs/rules/spot/version-enum.md b/docs/rules/spot/version-enum.md index dd76a69a8..3dae00df8 100644 --- a/docs/rules/spot/version-enum.md +++ b/docs/rules/spot/version-enum.md @@ -7,7 +7,7 @@ slug: /docs/cli/rules/spot/version-enum Requires the `version` property must be one of the supported values. | ARAZZO | Compatibility | -|--------| ------------- | +| ------ | ------------- | | 1.0.0 | ✅ | ```mermaid @@ -21,7 +21,7 @@ style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px ## API design principles This is `Spot` specific rule. -The `version` property must be one of the supported values witch is might be different to the `Arazzo` latest versions. +The `version` property must be one of the supported values witch is might be different to the `Arazzo` latest versions. ## Configuration @@ -64,4 +64,3 @@ arazzo: 1.0.0 ## Resources - [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/spot/version-enum.ts) - From ba802b97982d0dfc4578ecdbc6265c39d2afda23 Mon Sep 17 00:00:00 2001 From: dimaananskyi Date: Thu, 29 Aug 2024 19:16:28 +0300 Subject: [PATCH 03/23] chore: document requestBody-replacements-unique rule --- docs/rules/arazzo/parameters-unique.md | 4 +- .../arazzo/requestBody-replacements-unique.md | 87 +++++++++++++++++++ docs/rules/recommended.md | 1 + 3 files changed, 89 insertions(+), 3 deletions(-) create mode 100644 docs/rules/arazzo/requestBody-replacements-unique.md diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md index 391db8ee8..40f30feae 100644 --- a/docs/rules/arazzo/parameters-unique.md +++ b/docs/rules/arazzo/parameters-unique.md @@ -36,7 +36,7 @@ style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px ## API design principles -A list of `parameters` that are applicable for step or all steps described under workflow should not be duplicated to avoid shallow parameter override. +A list of `parameters` that are applicable to step or all steps described under workflow should not be duplicated to avoid shadow parameter override. ## Configuration @@ -88,8 +88,6 @@ workflows: value: Main Og== ``` -## Related rules - ## Resources - [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/parameters-unique.ts) diff --git a/docs/rules/arazzo/requestBody-replacements-unique.md b/docs/rules/arazzo/requestBody-replacements-unique.md new file mode 100644 index 000000000..7d7465c1d --- /dev/null +++ b/docs/rules/arazzo/requestBody-replacements-unique.md @@ -0,0 +1,87 @@ +--- +slug: /docs/cli/rules/arazzo/requestBody-replacements-unique +--- + +# requestBody-replacements-unique + +Requires the `replacements` of the `requestBody` object to be unique. + +| ARAZZO | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> workflows --> workflow --> steps --> step --> requestBody --> replacements + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +A list of locations and values to set within a payload must not have duplicates that might result in content override. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + requestBody-replacements-unique: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + requestBody-replacements-unique: error +``` + +Example of an **incorrect** license: + +```yaml Object example +workflows: + - workflowId: events-crud + steps: + - stepId: create-event + operationPath: $sourceDescriptions.museum-api#/paths/~1special-events/post + requestBody: + payload: + name: 'Mermaid Treasure Identification and Analysis' + description: 'Identify and analyze mermaid treasures' + replacements: + - target: name + value: 'new name' + - target: name + value: 'another name' +``` + +Example of a **correct** license: + +```yaml Object example +workflows: + - workflowId: events-crud + steps: + - stepId: create-event + operationPath: $sourceDescriptions.museum-api#/paths/~1special-events/post + requestBody: + payload: + name: 'Mermaid Treasure Identification and Analysis' + description: 'Identify and analyze mermaid treasures' + replacements: + - target: name + value: 'new name' + - target: description + value: 'another description' +``` + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/requestBody-replacements-unique.ts) diff --git a/docs/rules/recommended.md b/docs/rules/recommended.md index 0d80fae9f..f6038adb1 100644 --- a/docs/rules/recommended.md +++ b/docs/rules/recommended.md @@ -44,6 +44,7 @@ Warnings: - [tag-description](./tag-description.md) - [version-enum](./spot/version-enum.md) - [parameters-not-in-body](./spot/parameters-not-in-body.md) +- [requestBody-replacements-unique](./arazzo/requestBody-replacements-unique.md) ## Recommended strict ruleset From 09d0016a587c66230ece746a3a2691c9f716bff6 Mon Sep 17 00:00:00 2001 From: dimaananskyi Date: Fri, 30 Aug 2024 17:04:23 +0300 Subject: [PATCH 04/23] chore: document arazzo rules --- .../arazzo/sourceDescriptions-name-unique.md | 77 +++++++++++++++ docs/rules/arazzo/sourceDescriptions-type.md | 77 +++++++++++++++ docs/rules/arazzo/step-onFailure-unique.md | 98 +++++++++++++++++++ docs/rules/arazzo/step-onSuccess-unique.md | 98 +++++++++++++++++++ docs/rules/arazzo/stepId-unique.md | 84 ++++++++++++++++ docs/rules/arazzo/workflow-dependsOn.md | 73 ++++++++++++++ docs/rules/arazzo/workflowId-unique.md | 85 ++++++++++++++++ docs/rules/minimal.md | 2 + docs/rules/recommended.md | 7 ++ ...test.ts => sourceDescription-type.test.ts} | 0 packages/core/src/rules/arazzo/index.ts | 4 +- ...ion-type.ts => sourceDescriptions-type.ts} | 2 +- 12 files changed, 604 insertions(+), 3 deletions(-) create mode 100644 docs/rules/arazzo/sourceDescriptions-name-unique.md create mode 100644 docs/rules/arazzo/sourceDescriptions-type.md create mode 100644 docs/rules/arazzo/step-onFailure-unique.md create mode 100644 docs/rules/arazzo/step-onSuccess-unique.md create mode 100644 docs/rules/arazzo/stepId-unique.md create mode 100644 docs/rules/arazzo/workflow-dependsOn.md create mode 100644 docs/rules/arazzo/workflowId-unique.md rename packages/core/src/rules/arazzo/__tests__/{source-description-type.test.ts => sourceDescription-type.test.ts} (100%) rename packages/core/src/rules/arazzo/{source-description-type.ts => sourceDescriptions-type.ts} (91%) diff --git a/docs/rules/arazzo/sourceDescriptions-name-unique.md b/docs/rules/arazzo/sourceDescriptions-name-unique.md new file mode 100644 index 000000000..2a23f9d1c --- /dev/null +++ b/docs/rules/arazzo/sourceDescriptions-name-unique.md @@ -0,0 +1,77 @@ +--- +slug: /docs/cli/rules/arazzo/sourceDescription-name-unique +--- + +# sourceDescription-name-unique + +Requires the `name` property of the `sourceDescription` object must be unique across all source descriptions. + +| ARAZZO | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> sourceDescriptions --> sourceDescription --> name + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +To avoid confusion, each `sourceDescription` object should have a unique `name` property. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + sourceDescription-name-unique: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + sourceDescription-name-unique: error +``` + +Example of an **incorrect** sourceDescription: + +```yaml Object example +sourceDescriptions: + - name: museum-api + type: openapi + url: ../openapi.yaml + - name: museum-api + type: openapi + url: ../petstore.yaml +``` + +Example of a **correct** license: + +```yaml Object example +sourceDescriptions: + - name: museum-api + type: openapi + url: ../openapi.yaml + - name: pets-api + type: openapi + url: ../petstore.yaml +``` + +## Related rules + +- [sourceDescription-type](./sourceDescriptions-type) + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/sourceDescriptions-name-unique.ts) diff --git a/docs/rules/arazzo/sourceDescriptions-type.md b/docs/rules/arazzo/sourceDescriptions-type.md new file mode 100644 index 000000000..52c18ea25 --- /dev/null +++ b/docs/rules/arazzo/sourceDescriptions-type.md @@ -0,0 +1,77 @@ +--- +slug: /docs/cli/rules/arazzo/sourceDescription-type +--- + +# sourceDescription-type + +Requires the `type` property of the `sourceDescription` object must be either `openapi` or `arazzo`. + +| ARAZZO | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> sourceDescriptions --> sourceDescription --> type + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +By the Arazzo standard the possible values are "openapi" or "arazzo". + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + sourceDescription-type: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + sourceDescription-type: error +``` + +Example of an **incorrect** sourceDescription: + +```yaml Object example +sourceDescriptions: + - name: museum-api + type: openapi + url: ../openapi.yaml + - name: tickets-from-museum-api + type: none + x-serverUrl: 'http://localhost/api' +``` + +Example of a **correct** license: + +```yaml Object example +sourceDescriptions: + - name: museum-api + type: openapi + url: ../openapi.yaml + - name: tickets-from-museum-api + type: arazzo + url: museum-tickets.arazzo.yaml +``` + +## Related rules + +- [sourceDescription-name-unique](./sourceDescriptions-name-unique.md) + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/sourceDescription-type.ts) diff --git a/docs/rules/arazzo/step-onFailure-unique.md b/docs/rules/arazzo/step-onFailure-unique.md new file mode 100644 index 000000000..5a97b8c27 --- /dev/null +++ b/docs/rules/arazzo/step-onFailure-unique.md @@ -0,0 +1,98 @@ +--- +slug: /docs/cli/rules/arazzo/step-onFailure-unique +--- + +# step-onFailure-unique + +Requires the `onFailure` actions of the `step` object to be unique. + +| ARAZZO | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> workflows --> workflow --> steps --> step --> onFailure + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +An array of failure action objects that specify what to do upon step failure. +Each `onFailure` action should be unique to avoid confusion. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + step-onFailure-unique: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + step-onFailure-unique: error +``` + +Example of an **incorrect** step: + +```yaml Object example +workflows: +- workflowId: get-museum-hours + description: This workflow demonstrates how to get the museum opening hours and buy tickets. + steps: + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 + onFailure: + - name: test + workflowId: events-crud + type: goto + - name: test + workflowId: events-crud + type: goto + - reference: $components.failureActions.notify + - reference: $components.failureActions.notify +``` + +Example of a **correct** step: + +```yaml Object example +workflows: +- workflowId: get-museum-hours + description: This workflow demonstrates how to get the museum opening hours and buy tickets. + steps: + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 + onFailure: + - name: call-crud-events + workflowId: events-crud + type: goto + - name: second-call-crud-events + workflowId: events-crud + type: goto + - reference: $components.failureActions.notify + - reference: $components.failureActions.report +``` + +## Related rules + +- [step-onSuccess-unique](./step-onSuccess-unique.md) + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/step-onFailure-unique.ts) diff --git a/docs/rules/arazzo/step-onSuccess-unique.md b/docs/rules/arazzo/step-onSuccess-unique.md new file mode 100644 index 000000000..d57e53e45 --- /dev/null +++ b/docs/rules/arazzo/step-onSuccess-unique.md @@ -0,0 +1,98 @@ +--- +slug: /docs/cli/rules/arazzo/step-onSuccess-unique +--- + +# step-onSuccess-unique + +Requires the `onSuccess` actions of the `step` object to be unique. + +| ARAZZO | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> workflows --> workflow --> steps --> step --> onSuccess + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +An array of success action objects that specify what to do upon step success. +Each `onSuccess` action should be unique to avoid confusion. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + step-onSuccess-unique: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + step-onSuccess-unique: error +``` + +Example of an **incorrect** step: + +```yaml Object example +workflows: +- workflowId: get-museum-hours + description: This workflow demonstrates how to get the museum opening hours and buy tickets. + steps: + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 + onSuccess: + - name: test + workflowId: events-crud + type: goto + - name: test + workflowId: events-crud + type: goto + - reference: $components.successActions.notify + - reference: $components.successActions.notify +``` + +Example of a **correct** step: + +```yaml Object example +workflows: +- workflowId: get-museum-hours + description: This workflow demonstrates how to get the museum opening hours and buy tickets. + steps: + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 + onSuccess: + - name: call-crud-events + workflowId: events-crud + type: goto + - name: second-call-crud-events + workflowId: events-crud + type: goto + - reference: $components.successActions.notify + - reference: $components.successActions.report +``` + +## Related rules + +- [step-onFailure-unique](./step-onFailure-unique.md) + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/step-onSuccess-unique.ts) diff --git a/docs/rules/arazzo/stepId-unique.md b/docs/rules/arazzo/stepId-unique.md new file mode 100644 index 000000000..c002ab034 --- /dev/null +++ b/docs/rules/arazzo/stepId-unique.md @@ -0,0 +1,84 @@ +--- +slug: /docs/cli/rules/arazzo/stepId-unique +--- + +# stepId-unique + +Requires the `stepId` to be unique amongst all steps described in the workflow. + +| ARAZZO | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> workflows --> workflow --> steps --> step --> stepId + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +Unique string to represent the step. The `stepId` must be unique amongst all steps described in the workflow. +The stepId value is case-sensitive. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + stepId-unique: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + stepId-unique: error +``` + +Example of an **incorrect** step: + +```yaml Object example +workflows: + - workflowId: get-museum-hours-2 + description: This workflow demonstrates how to get the museum opening hours and buy tickets. + steps: + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 +``` + +Example of a **correct** step: + +```yaml Object example +workflows: + - workflowId: get-museum-hours-2 + description: This workflow demonstrates how to get the museum opening hours and buy tickets. + steps: + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 + - stepId: another-step-id + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 +``` + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/stepId-unique.ts) diff --git a/docs/rules/arazzo/workflow-dependsOn.md b/docs/rules/arazzo/workflow-dependsOn.md new file mode 100644 index 000000000..338cd99d5 --- /dev/null +++ b/docs/rules/arazzo/workflow-dependsOn.md @@ -0,0 +1,73 @@ +--- +slug: /docs/cli/rules/arazzo/workflow-dependsOn +--- + +# workflow-dependsOn + +Requires the items in the `workflow` `dependsOn` property to exist and to be unique. + +| ARAZZO | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> workflows --> workflow --> dependsOn + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +A list of workflows that should be completed before current workflow can be processed. +To avoid ambiguity or potential clashes, the `dependsOn` property should be unique. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + workflow-dependsOn: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + stepId-unique: error +``` + +Example of an **incorrect** step: + +```yaml Object example +workflows: + - workflowId: get-museum-hours + description: This workflow demonstrates how to get the museum opening hours and buy tickets. + dependsOn: + - get-museum-hours-2 + - get-museum-hours-3 + - get-museum-hours-2 +``` + +Example of a **correct** step: + +```yaml Object example +workflows: + - workflowId: get-museum-hours + description: This workflow demonstrates how to get the museum opening hours and buy tickets. + dependsOn: + - get-museum-hours-2 + - get-museum-hours-3 +``` + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/workflow-dependsOn.ts) diff --git a/docs/rules/arazzo/workflowId-unique.md b/docs/rules/arazzo/workflowId-unique.md new file mode 100644 index 000000000..a98745333 --- /dev/null +++ b/docs/rules/arazzo/workflowId-unique.md @@ -0,0 +1,85 @@ +--- +slug: /docs/cli/rules/arazzo/workflowId-unique +--- + +# workflowId-unique + +Requires the `workflowId` property to be unique across all workflows. + +| ARAZZO | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +```mermaid +flowchart TD + +Root ==> workflows --> workflow --> workflowId + +style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +Unique string to represent the workflow. The `workflowId` must be unique across all workflows described in the API definition. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +arazzoRules: + workflowId-unique: error +``` + +## Examples + +Given the following configuration: + +```yaml +arazzoRules: + workflowId-unique: error +``` + +Example of an **incorrect** step: + +```yaml Object example +workflows: + - workflowId: get-museum-hours + steps: + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 + - workflowId: get-museum-hours + steps: + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 +``` + +Example of a **correct** step: + +```yaml Object example +workflows: + - workflowId: get-museum-hours + steps: + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 + - workflowId: get-museum-hours-routine + steps: + - stepId: get-museum-hours + operationId: museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 +``` + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/workflowId-unique.ts) diff --git a/docs/rules/minimal.md b/docs/rules/minimal.md index b3388733d..ab0dadcb2 100644 --- a/docs/rules/minimal.md +++ b/docs/rules/minimal.md @@ -12,6 +12,8 @@ Errors: - [no-server-variables-empty-enum](./no-server-variables-empty-enum.md) - [no-unresolved-refs](./no-unresolved-refs.md) - [spec](./spec.md) +- [stepId-unique](./arazzo/stepId-unique.md) +- [workflowId-unique](./arazzo/workflowId-unique.md) Warnings: diff --git a/docs/rules/recommended.md b/docs/rules/recommended.md index f6038adb1..9dc634c95 100644 --- a/docs/rules/recommended.md +++ b/docs/rules/recommended.md @@ -28,6 +28,11 @@ Errors: - [spec-components-invalid-map-name](./spec-components-invalid-map-name.md) - [spec](./spec.md) - [parameters-unique](./arazzo/parameters-unique.md) +- [sourceDescription-type](./arazzo/sourceDescriptions-type) +- [sourceDescription-name-unique](./arazzo/sourceDescriptions-name-unique.md) +- [stepId-unique](./arazzo/stepId-unique.md) +- [workflow-dependsOn](./arazzo/workflow-dependsOn.md) +- [workflowId-unique](./arazzo/workflowId-unique.md) Warnings: @@ -45,6 +50,8 @@ Warnings: - [version-enum](./spot/version-enum.md) - [parameters-not-in-body](./spot/parameters-not-in-body.md) - [requestBody-replacements-unique](./arazzo/requestBody-replacements-unique.md) +- [step-onFailure-unique](./arazzo/step-onFailure-unique.md) +- [step-onSuccess-unique](./arazzo/step-onSuccess-unique.md) ## Recommended strict ruleset diff --git a/packages/core/src/rules/arazzo/__tests__/source-description-type.test.ts b/packages/core/src/rules/arazzo/__tests__/sourceDescription-type.test.ts similarity index 100% rename from packages/core/src/rules/arazzo/__tests__/source-description-type.test.ts rename to packages/core/src/rules/arazzo/__tests__/sourceDescription-type.test.ts diff --git a/packages/core/src/rules/arazzo/index.ts b/packages/core/src/rules/arazzo/index.ts index c00261a2f..06981d49c 100644 --- a/packages/core/src/rules/arazzo/index.ts +++ b/packages/core/src/rules/arazzo/index.ts @@ -1,7 +1,7 @@ import { Spec } from '../common/spec'; import { Assertions } from '../common/assertions'; import { ParametersNotInBody } from '../spot/parameters-not-in-body'; -import { SourceDescriptionType } from '../arazzo/source-description-type'; +import { SourceDescriptionsType } from './sourceDescriptions-type'; import { VersionEnum } from '../spot/version-enum'; import { WorkflowIdUnique } from './workflowId-unique'; import { StepIdUnique } from './stepId-unique'; @@ -22,7 +22,7 @@ export const rules: ArazzoRuleSet<'built-in'> = { spec: Spec as ArazzoRule, assertions: Assertions as ArazzoRule, 'parameters-not-in-body': ParametersNotInBody as ArazzoRule, - 'sourceDescription-type': SourceDescriptionType as ArazzoRule, + 'sourceDescription-type': SourceDescriptionsType as ArazzoRule, 'version-enum': VersionEnum as ArazzoRule, 'workflowId-unique': WorkflowIdUnique as ArazzoRule, 'stepId-unique': StepIdUnique as ArazzoRule, diff --git a/packages/core/src/rules/arazzo/source-description-type.ts b/packages/core/src/rules/arazzo/sourceDescriptions-type.ts similarity index 91% rename from packages/core/src/rules/arazzo/source-description-type.ts rename to packages/core/src/rules/arazzo/sourceDescriptions-type.ts index efc433139..e5cd61916 100644 --- a/packages/core/src/rules/arazzo/source-description-type.ts +++ b/packages/core/src/rules/arazzo/sourceDescriptions-type.ts @@ -1,7 +1,7 @@ import type { ArazzoRule } from '../../visitors'; import type { UserContext } from '../../walk'; -export const SourceDescriptionType: ArazzoRule = () => { +export const SourceDescriptionsType: ArazzoRule = () => { return { SourceDescriptions: { enter(SourceDescriptions, { report, location }: UserContext) { From c59483deb569220cb59fdd58fab5b65a5c8d6e81 Mon Sep 17 00:00:00 2001 From: dimaananskyi Date: Fri, 30 Aug 2024 17:58:44 +0300 Subject: [PATCH 05/23] chore: document async rules --- docs/guides/lint-asyncapi.md | 4 +- docs/rules/async/channels-kebab-case.md | 71 ++++++++++++++++++ docs/rules/async/no-channel-trailing-slash.md | 72 +++++++++++++++++++ docs/rules/spec.md | 9 +++ 4 files changed, 154 insertions(+), 2 deletions(-) create mode 100644 docs/rules/async/channels-kebab-case.md create mode 100644 docs/rules/async/no-channel-trailing-slash.md diff --git a/docs/guides/lint-asyncapi.md b/docs/guides/lint-asyncapi.md index 9de216818..6eeb4732b 100644 --- a/docs/guides/lint-asyncapi.md +++ b/docs/guides/lint-asyncapi.md @@ -53,8 +53,8 @@ some of the built-in rules. The currently-supported rules are: - `info-contact`: the `Info` section must contain a valid `Contact` field. - `operation-operationId`: every operation must have a valid `operationId`. -- `channels-kebab-case`: channel names should be `kebab-case` (lowercase with hyphens). -- `no-channel-trailing-slash`: channel names must not have trailing slashes in their names. +- `channels-kebab-case`: channel address should be `kebab-case` (lowercase with hyphens). +- `no-channel-trailing-slash`: channel names must not have trailing slashes in their address. - `tag-description`: all tags require a description. - `tags-alphabetical`: tags should be listed in the AsyncAPI file in alphabetical order. diff --git a/docs/rules/async/channels-kebab-case.md b/docs/rules/async/channels-kebab-case.md new file mode 100644 index 000000000..aaa848338 --- /dev/null +++ b/docs/rules/async/channels-kebab-case.md @@ -0,0 +1,71 @@ +--- +slug: /docs/cli/rules/async/channels-kebab-case +--- + +# channels-kebab-case + +Channel address should be `kebab-case` (lowercase with hyphens). + +| AsyncAPI | Compatibility | +| -------- | ------------- | +| 2.0 | ✅ | +| 3.0 | ✅ | + +```mermaid +flowchart TD + +root ==> channels --> channel --> address + +style url fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +Channel address should be `kebab-case` (lowercase with hyphens). + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +rules: + channels-kebab-case: error +``` + +## Examples + +Given the following configuration: + +```yaml +rules: + channels-kebab-case: error +``` + +Example of an **incorrect** channel: + +```yaml +channels: + channel1: + address: /NOT_A_KEBAB/ + payload: + type: object +``` + +Example of a **correct** channel: + +```yaml +channels: + channel1: + address: kebab-with-longer-channel-path + payload: + type: object +``` + +## Resources + +- [Rule source async3](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/async3/channels-kebab-case.ts) +- [Rule source async2](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/async2/channels-kebab-case.ts) diff --git a/docs/rules/async/no-channel-trailing-slash.md b/docs/rules/async/no-channel-trailing-slash.md new file mode 100644 index 000000000..e5e12c15e --- /dev/null +++ b/docs/rules/async/no-channel-trailing-slash.md @@ -0,0 +1,72 @@ +--- +slug: /docs/cli/rules/async/no-channel-trailing-slash +--- + +# no-channel-trailing-slash + +Channel names must not have trailing slashes in their address. + +| AsyncAPI | Compatibility | +| -------- | ------------- | +| 2.0 | ✅ | +| 3.0 | ✅ | + +```mermaid +flowchart TD + +root ==> channels --> channel --> address + +style url fill:#codaf9,stroke:#0044d4,stroke-width:5px +``` + +## API design principles + +Channel names must not have trailing slashes in their address. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +rules: + no-channel-trailing-slash: error + +``` + +## Examples + +Given the following configuration: + +```yaml +rules: + no-channel-trailing-slash: error +``` + +Example of an **incorrect** channel: + +```yaml +channels: + channel1: + address: /trailing/ + payload: + type: object +``` + +Example of a **correct** channel: + +```yaml +channels: + channel1: + address: /expected + payload: + type: object +``` + +## Resources + +- [Rule source async3](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/async3/no-channel-trailing-slash.ts) +- [Rule source async2](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/async2/no-channel-trailing-slash.ts) diff --git a/docs/rules/spec.md b/docs/rules/spec.md index c7e2d9697..319db0c35 100644 --- a/docs/rules/spec.md +++ b/docs/rules/spec.md @@ -12,6 +12,15 @@ Ensures that your API document conforms to the [OpenAPI specification](https://s | 3.0 | ✅ | | 3.1 | ✅ | +| ARAZZO | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +| ASYNC | Compatibility | +| ----- | ------------- | +| 2.0 | ✅ | +| 3.0 | ✅ | + The default setting for this rule (in the `recommended` and `minimal` configuration) is `error`. This is an essential rule that should not be turned off except in rare and special cases. From fb35ae13dd08fd00fe5e500e0e2ebb7eaaa419eb Mon Sep 17 00:00:00 2001 From: dimaananskyi Date: Fri, 30 Aug 2024 18:12:20 +0300 Subject: [PATCH 06/23] chore: update links --- docs/rules/arazzo/sourceDescriptions-name-unique.md | 2 +- docs/rules/recommended.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rules/arazzo/sourceDescriptions-name-unique.md b/docs/rules/arazzo/sourceDescriptions-name-unique.md index 2a23f9d1c..86add3884 100644 --- a/docs/rules/arazzo/sourceDescriptions-name-unique.md +++ b/docs/rules/arazzo/sourceDescriptions-name-unique.md @@ -70,7 +70,7 @@ sourceDescriptions: ## Related rules -- [sourceDescription-type](./sourceDescriptions-type) +- [sourceDescription-type](./sourceDescriptions-type.md) ## Resources diff --git a/docs/rules/recommended.md b/docs/rules/recommended.md index 9dc634c95..87c6aae90 100644 --- a/docs/rules/recommended.md +++ b/docs/rules/recommended.md @@ -28,7 +28,7 @@ Errors: - [spec-components-invalid-map-name](./spec-components-invalid-map-name.md) - [spec](./spec.md) - [parameters-unique](./arazzo/parameters-unique.md) -- [sourceDescription-type](./arazzo/sourceDescriptions-type) +- [sourceDescription-type](./arazzo/sourceDescriptions-type.md) - [sourceDescription-name-unique](./arazzo/sourceDescriptions-name-unique.md) - [stepId-unique](./arazzo/stepId-unique.md) - [workflow-dependsOn](./arazzo/workflow-dependsOn.md) From 866978a1ef43aa3e8d918aadc680b8f0bd85b882 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Thu, 5 Sep 2024 12:04:18 +0100 Subject: [PATCH 07/23] Apply suggestions from code review Co-authored-by: Adam Altman --- docs/rules/arazzo/parameters-unique.md | 2 +- docs/rules/spec.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md index 40f30feae..3b12c4b7b 100644 --- a/docs/rules/arazzo/parameters-unique.md +++ b/docs/rules/arazzo/parameters-unique.md @@ -6,7 +6,7 @@ slug: /docs/cli/rules/arazzo/parameters-unique Requires the `parameters` list not to include duplicate parameters. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | diff --git a/docs/rules/spec.md b/docs/rules/spec.md index 319db0c35..a8f582b50 100644 --- a/docs/rules/spec.md +++ b/docs/rules/spec.md @@ -12,7 +12,7 @@ Ensures that your API document conforms to the [OpenAPI specification](https://s | 3.0 | ✅ | | 3.1 | ✅ | -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | From 7b024e681d45dac418ded16352a9a2e79873a35c Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Thu, 5 Sep 2024 16:56:37 +0100 Subject: [PATCH 08/23] docs: copyedit, remove diagrams and page slugs, update for accuracy --- docs/rules/arazzo/parameters-unique.md | 41 +++++-------------- .../arazzo/requestBody-replacements-unique.md | 22 +++------- .../arazzo/sourceDescriptions-name-unique.md | 20 ++------- docs/rules/arazzo/sourceDescriptions-type.md | 22 +++------- docs/rules/arazzo/step-onFailure-unique.md | 18 ++------ docs/rules/arazzo/step-onSuccess-unique.md | 16 +------- docs/rules/arazzo/stepId-unique.md | 19 ++------- docs/rules/arazzo/workflow-dependsOn.md | 16 +------- docs/rules/arazzo/workflowId-unique.md | 21 +++------- docs/rules/async/channels-kebab-case.md | 12 ------ docs/rules/async/no-channel-trailing-slash.md | 12 ------ docs/rules/minimal.md | 4 -- docs/rules/recommended.md | 4 -- docs/rules/spec.md | 12 ++---- docs/rules/spot/parameters-not-in-body.md | 41 ++++--------------- docs/rules/spot/version-enum.md | 24 +++-------- 16 files changed, 59 insertions(+), 245 deletions(-) diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md index 3b12c4b7b..6a7c90fbe 100644 --- a/docs/rules/arazzo/parameters-unique.md +++ b/docs/rules/arazzo/parameters-unique.md @@ -1,42 +1,21 @@ ---- -slug: /docs/cli/rules/arazzo/parameters-unique ---- - # parameters-unique -Requires the `parameters` list not to include duplicate parameters. +Requires unique values in the `parameters` lists. | Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> workflows --> workflow --> parameters - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - -```mermaid -flowchart TD - -Root ==> x-parameters - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - -```mermaid -flowchart TD - -Root ==> workflows --> workflow --> steps --> step --> parameters +## API design principles -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` +A list of `parameters` that are applicable to a step or all the steps described in a workflow should not contain duplicates. +If duplicates are present, unexpected parameter overrides could cause problems. -## API design principles +Checks parameter lists in the following locations: -A list of `parameters` that are applicable to step or all steps described under workflow should not be duplicated to avoid shadow parameter override. +- `workflows.[workflow].parameters` +- `workflows.[workflow[.steps.[step].parameters` +- `x-parameters` ## Configuration @@ -60,7 +39,7 @@ arazzoRules: parameters-unique: error ``` -Example of an **incorrect** license: +Example of an **incorrect** parameters array: ```yaml Object example workflows: @@ -74,7 +53,7 @@ workflows: value: Basic Og== ``` -Example of a **correct** license: +Example of a **correct** parameters array: ```yaml Object example workflows: diff --git a/docs/rules/arazzo/requestBody-replacements-unique.md b/docs/rules/arazzo/requestBody-replacements-unique.md index 7d7465c1d..306fade58 100644 --- a/docs/rules/arazzo/requestBody-replacements-unique.md +++ b/docs/rules/arazzo/requestBody-replacements-unique.md @@ -1,26 +1,14 @@ ---- -slug: /docs/cli/rules/arazzo/requestBody-replacements-unique ---- - # requestBody-replacements-unique -Requires the `replacements` of the `requestBody` object to be unique. +Requires the `replacements` in the `step.requestBody` object to be unique. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> workflows --> workflow --> steps --> step --> requestBody --> replacements - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles -A list of locations and values to set within a payload must not have duplicates that might result in content override. +The list of locations and values to set within a payload must not have duplicates that might result in content override. ## Configuration @@ -44,7 +32,7 @@ arazzoRules: requestBody-replacements-unique: error ``` -Example of an **incorrect** license: +Example of an **incorrect** replacements array: ```yaml Object example workflows: @@ -63,7 +51,7 @@ workflows: value: 'another name' ``` -Example of a **correct** license: +Example of a **correct** replacements array: ```yaml Object example workflows: diff --git a/docs/rules/arazzo/sourceDescriptions-name-unique.md b/docs/rules/arazzo/sourceDescriptions-name-unique.md index 86add3884..465f6af1d 100644 --- a/docs/rules/arazzo/sourceDescriptions-name-unique.md +++ b/docs/rules/arazzo/sourceDescriptions-name-unique.md @@ -1,26 +1,14 @@ ---- -slug: /docs/cli/rules/arazzo/sourceDescription-name-unique ---- - # sourceDescription-name-unique Requires the `name` property of the `sourceDescription` object must be unique across all source descriptions. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> sourceDescriptions --> sourceDescription --> name - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles -To avoid confusion, each `sourceDescription` object should have a unique `name` property. +To avoid confusion or unexpected outputs, each `sourceDescription` object should have a unique `name` property. ## Configuration @@ -44,7 +32,7 @@ arazzoRules: sourceDescription-name-unique: error ``` -Example of an **incorrect** sourceDescription: +Example of an **incorrect** sourceDescriptions array: ```yaml Object example sourceDescriptions: @@ -56,7 +44,7 @@ sourceDescriptions: url: ../petstore.yaml ``` -Example of a **correct** license: +Example of a **correct** sourceDescriptions array: ```yaml Object example sourceDescriptions: diff --git a/docs/rules/arazzo/sourceDescriptions-type.md b/docs/rules/arazzo/sourceDescriptions-type.md index 52c18ea25..ca1b88723 100644 --- a/docs/rules/arazzo/sourceDescriptions-type.md +++ b/docs/rules/arazzo/sourceDescriptions-type.md @@ -1,26 +1,14 @@ ---- -slug: /docs/cli/rules/arazzo/sourceDescription-type ---- - # sourceDescription-type -Requires the `type` property of the `sourceDescription` object must be either `openapi` or `arazzo`. +The `type` property of the `sourceDescription` object must be either `openapi` or `arazzo`. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> sourceDescriptions --> sourceDescription --> type - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles -By the Arazzo standard the possible values are "openapi" or "arazzo". +By the Arazzo standard the possible values for `sourceDescription.type` are "openapi" or "arazzo". ## Configuration @@ -44,7 +32,7 @@ arazzoRules: sourceDescription-type: error ``` -Example of an **incorrect** sourceDescription: +Example of an **incorrect** sourceDescriptions array: ```yaml Object example sourceDescriptions: @@ -56,7 +44,7 @@ sourceDescriptions: x-serverUrl: 'http://localhost/api' ``` -Example of a **correct** license: +Example of a **correct** sourceDescriptions array: ```yaml Object example sourceDescriptions: diff --git a/docs/rules/arazzo/step-onFailure-unique.md b/docs/rules/arazzo/step-onFailure-unique.md index 5a97b8c27..57cfb00dc 100644 --- a/docs/rules/arazzo/step-onFailure-unique.md +++ b/docs/rules/arazzo/step-onFailure-unique.md @@ -1,27 +1,15 @@ ---- -slug: /docs/cli/rules/arazzo/step-onFailure-unique ---- - # step-onFailure-unique -Requires the `onFailure` actions of the `step` object to be unique. +Requires all of the `onFailure` actions of the `step` object to be unique. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> workflows --> workflow --> steps --> step --> onFailure - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles An array of failure action objects that specify what to do upon step failure. -Each `onFailure` action should be unique to avoid confusion. +Each `onFailure` action should be unique to avoid confusion or unexpected results. ## Configuration diff --git a/docs/rules/arazzo/step-onSuccess-unique.md b/docs/rules/arazzo/step-onSuccess-unique.md index d57e53e45..db8ed0d47 100644 --- a/docs/rules/arazzo/step-onSuccess-unique.md +++ b/docs/rules/arazzo/step-onSuccess-unique.md @@ -1,27 +1,15 @@ ---- -slug: /docs/cli/rules/arazzo/step-onSuccess-unique ---- - # step-onSuccess-unique Requires the `onSuccess` actions of the `step` object to be unique. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> workflows --> workflow --> steps --> step --> onSuccess - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles An array of success action objects that specify what to do upon step success. -Each `onSuccess` action should be unique to avoid confusion. +Each `onSuccess` action should be unique to avoid confusion or unexpected outcomes. ## Configuration diff --git a/docs/rules/arazzo/stepId-unique.md b/docs/rules/arazzo/stepId-unique.md index c002ab034..8d88644b7 100644 --- a/docs/rules/arazzo/stepId-unique.md +++ b/docs/rules/arazzo/stepId-unique.md @@ -1,27 +1,16 @@ ---- -slug: /docs/cli/rules/arazzo/stepId-unique ---- - # stepId-unique Requires the `stepId` to be unique amongst all steps described in the workflow. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> workflows --> workflow --> steps --> step --> stepId - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles -Unique string to represent the step. The `stepId` must be unique amongst all steps described in the workflow. -The stepId value is case-sensitive. +Unique string to represent the step. +The `stepId` must be unique amongst all steps described in the workflow. +The `stepId` value is case-sensitive. ## Configuration diff --git a/docs/rules/arazzo/workflow-dependsOn.md b/docs/rules/arazzo/workflow-dependsOn.md index 338cd99d5..558e3b7c4 100644 --- a/docs/rules/arazzo/workflow-dependsOn.md +++ b/docs/rules/arazzo/workflow-dependsOn.md @@ -1,7 +1,3 @@ ---- -slug: /docs/cli/rules/arazzo/workflow-dependsOn ---- - # workflow-dependsOn Requires the items in the `workflow` `dependsOn` property to exist and to be unique. @@ -10,14 +6,6 @@ Requires the items in the `workflow` `dependsOn` property to exist and to be uni | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> workflows --> workflow --> dependsOn - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles A list of workflows that should be completed before current workflow can be processed. @@ -45,7 +33,7 @@ arazzoRules: stepId-unique: error ``` -Example of an **incorrect** step: +Example of an **incorrect** `dependsOn` array: ```yaml Object example workflows: @@ -57,7 +45,7 @@ workflows: - get-museum-hours-2 ``` -Example of a **correct** step: +Example of a **correct** `dependsOn` array: ```yaml Object example workflows: diff --git a/docs/rules/arazzo/workflowId-unique.md b/docs/rules/arazzo/workflowId-unique.md index a98745333..63a38bb88 100644 --- a/docs/rules/arazzo/workflowId-unique.md +++ b/docs/rules/arazzo/workflowId-unique.md @@ -1,26 +1,15 @@ ---- -slug: /docs/cli/rules/arazzo/workflowId-unique ---- - # workflowId-unique Requires the `workflowId` property to be unique across all workflows. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> workflows --> workflow --> workflowId - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles -Unique string to represent the workflow. The `workflowId` must be unique across all workflows described in the API definition. +Unique string to represent the workflow. +The `workflowId` must be unique across all workflows described in the API definition. ## Configuration @@ -44,7 +33,7 @@ arazzoRules: workflowId-unique: error ``` -Example of an **incorrect** step: +Example of an **incorrect** `workflows` array: ```yaml Object example workflows: @@ -62,7 +51,7 @@ workflows: - condition: $statusCode == 200 ``` -Example of a **correct** step: +Example of a **correct** `workflows` array: ```yaml Object example workflows: diff --git a/docs/rules/async/channels-kebab-case.md b/docs/rules/async/channels-kebab-case.md index aaa848338..cb7396e16 100644 --- a/docs/rules/async/channels-kebab-case.md +++ b/docs/rules/async/channels-kebab-case.md @@ -1,7 +1,3 @@ ---- -slug: /docs/cli/rules/async/channels-kebab-case ---- - # channels-kebab-case Channel address should be `kebab-case` (lowercase with hyphens). @@ -11,14 +7,6 @@ Channel address should be `kebab-case` (lowercase with hyphens). | 2.0 | ✅ | | 3.0 | ✅ | -```mermaid -flowchart TD - -root ==> channels --> channel --> address - -style url fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles Channel address should be `kebab-case` (lowercase with hyphens). diff --git a/docs/rules/async/no-channel-trailing-slash.md b/docs/rules/async/no-channel-trailing-slash.md index e5e12c15e..bd29924f4 100644 --- a/docs/rules/async/no-channel-trailing-slash.md +++ b/docs/rules/async/no-channel-trailing-slash.md @@ -1,7 +1,3 @@ ---- -slug: /docs/cli/rules/async/no-channel-trailing-slash ---- - # no-channel-trailing-slash Channel names must not have trailing slashes in their address. @@ -11,14 +7,6 @@ Channel names must not have trailing slashes in their address. | 2.0 | ✅ | | 3.0 | ✅ | -```mermaid -flowchart TD - -root ==> channels --> channel --> address - -style url fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles Channel names must not have trailing slashes in their address. diff --git a/docs/rules/minimal.md b/docs/rules/minimal.md index ab0dadcb2..78ad2fdd3 100644 --- a/docs/rules/minimal.md +++ b/docs/rules/minimal.md @@ -1,7 +1,3 @@ ---- -slug: /docs/cli/rules/minimal ---- - # Minimal ruleset The rules contained in the minimal ruleset: diff --git a/docs/rules/recommended.md b/docs/rules/recommended.md index 87c6aae90..c6d3b69f4 100644 --- a/docs/rules/recommended.md +++ b/docs/rules/recommended.md @@ -1,7 +1,3 @@ ---- -slug: /docs/cli/rules/recommended ---- - # Recommended ruleset These are the rules in the `recommended` set, grouped by their severity. diff --git a/docs/rules/spec.md b/docs/rules/spec.md index a8f582b50..440bae0fe 100644 --- a/docs/rules/spec.md +++ b/docs/rules/spec.md @@ -1,7 +1,3 @@ ---- -slug: /docs/cli/rules/spec ---- - # spec Ensures that your API document conforms to the [OpenAPI specification](https://spec.openapis.org/oas/v3.1.0.html). @@ -16,10 +12,10 @@ Ensures that your API document conforms to the [OpenAPI specification](https://s | ------ | ------------- | | 1.0.0 | ✅ | -| ASYNC | Compatibility | -| ----- | ------------- | -| 2.0 | ✅ | -| 3.0 | ✅ | +| AsyncAPI | Compatibility | +| -------- | ------------- | +| 2.0 | ✅ | +| 3.0 | ✅ | The default setting for this rule (in the `recommended` and `minimal` configuration) is `error`. diff --git a/docs/rules/spot/parameters-not-in-body.md b/docs/rules/spot/parameters-not-in-body.md index 3e9a6d213..12709125f 100644 --- a/docs/rules/spot/parameters-not-in-body.md +++ b/docs/rules/spot/parameters-not-in-body.md @@ -1,43 +1,20 @@ ---- -slug: /docs/cli/rules/spot/parameters-not-in-body ---- - # parameters-not-in-body Requires the `in` section inside `parameters` must not contain a `body`. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> workflows --> workflow --> parameters - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - -```mermaid -flowchart TD - -Root ==> x-parameters - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - -```mermaid -flowchart TD - -Root ==> workflows --> workflow --> steps --> step --> parameters - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles -This is `Spot` specific rule. +This is rule is specific to the Spot tool. `body` is not supported in the `in` section inside `parameters`. +This affects parameter lists in: + +- `workflows.[workflow].parameters` +- `workflows.[workflow[.steps.[step].parameters` +- `x-parameters` ## Configuration @@ -61,7 +38,7 @@ arazzoRules: parameters-not-in-body: error ``` -Example of an **incorrect** license: +Example of an **incorrect** list of `parameters`: ```yaml Object example workflows: @@ -72,7 +49,7 @@ workflows: value: Basic Og== ``` -Example of a **correct** license: +Example of a **correct** list of `parameters`: ```yaml Object example workflows: diff --git a/docs/rules/spot/version-enum.md b/docs/rules/spot/version-enum.md index 3dae00df8..fac20d762 100644 --- a/docs/rules/spot/version-enum.md +++ b/docs/rules/spot/version-enum.md @@ -1,27 +1,15 @@ ---- -slug: /docs/cli/rules/spot/version-enum ---- - # version-enum Requires the `version` property must be one of the supported values. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -```mermaid -flowchart TD - -Root ==> arazzo - -style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px -``` - ## API design principles -This is `Spot` specific rule. -The `version` property must be one of the supported values witch is might be different to the `Arazzo` latest versions. +This rule is used with Spot. +The `version` property must be one of the Spot-supported values which may be different to the latest `Arazzo` version. ## Configuration @@ -45,13 +33,13 @@ arazzoRules: version-enum: error ``` -Example of an **incorrect** license: +Example of an **incorrect** entry: ```yaml Object example -arazzo: 1.0.1 +arazzo: 4.2.0 ``` -Example of a **correct** license: +Example of a **correct** entry: ```yaml Object example arazzo: 1.0.0 From f83e4c09e20e546f94c7869d3fa66fe961eb08bd Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 4 Oct 2024 11:20:14 +0100 Subject: [PATCH 09/23] docs: add new rules to built-in rules page, add format grouping --- docs/rules/arazzo/criteria-unique.md | 4 -- docs/rules/built-in-rules.md | 45 ++++++++++++++++++- ...ired-string-property-missing-min-length.md | 2 +- docs/rules/scalar-property-missing-example.md | 2 +- docs/rules/spec-strict-refs.md | 2 +- docs/rules/tag-description.md | 2 +- 6 files changed, 47 insertions(+), 10 deletions(-) diff --git a/docs/rules/arazzo/criteria-unique.md b/docs/rules/arazzo/criteria-unique.md index 9cff899c3..d827cacaa 100644 --- a/docs/rules/arazzo/criteria-unique.md +++ b/docs/rules/arazzo/criteria-unique.md @@ -1,7 +1,3 @@ ---- -slug: /docs/cli/rules/arazzo/criteria-unique ---- - # criteria-unique The criteria list must not contain duplicated assertions. diff --git a/docs/rules/built-in-rules.md b/docs/rules/built-in-rules.md index 93576ce6b..6bf28eab1 100644 --- a/docs/rules/built-in-rules.md +++ b/docs/rules/built-in-rules.md @@ -13,9 +13,19 @@ The _Special rules_ group contains rules that may apply to multiple objects or t Build [configurable rules](./configurable-rules.md) if the rule you need isn't listed. {% /admonition %} -## List of available rules +## Per-format rules -Details of all the rules available "out of the box" with Redocly CLI are listed below. Visit each individual page for details of what the rule does, additional configuration options, and examples of it in use. +Redocly CLI can lint multiple API description formats: + +- [OpenAPI](#openapi-rules) +- [AsyncAPI](#asyncapi-rules) +- [Arazzo](#arazzo-rules) + +Visit each page for details of what the rule does, additional configuration options, and examples of it in use. + +## OpenAPI rules + +The rules list is split into sections. ### Special rules @@ -91,6 +101,37 @@ Details of all the rules available "out of the box" with Redocly CLI are listed - [tag-description](./tag-description.md): Tags must have descriptions - [tags-alphabetical](./tags-alphabetical.md): Tags in the top-level `tags` section must appear alphabetically +## AsyncAPI rules + +- [no-channel-trailing-slash](./async/no-channel-trailing-slash.md) +- [channels-kebab-case](./async/channels-kebab-case.md) + +## Arazzo rules + +Within the Arazzo family of rules, there are rules for the main Arazzo specification format, and some additional rules for extensions supported by Spot, the Redocly testing utility. + +### Arazzo + +- [parameters-unique](./arazzo/parameters-unique.md) +- [step-onSuccess-unique](./arazzo/step-onSuccess-unique.md) +- [workflow-dependsOn](./arazzo/workflow-dependsOn.md) +- [sourceDescriptions-type](./arazzo/sourceDescriptions-type.md) +- [step-onFailure-unique](./arazzo/step-onFailure-unique.md) +- [sourceDescriptions-name-unique](./arazzo/sourceDescriptions-name-unique.md) +- [stepId-unique](./arazzo/stepId-unique.md) +- [criteria-unique](./arazzo/criteria-unique.md) +- [requestBody-replacements-unique](./arazzo/requestBody-replacements-unique.md) +- [workflowId-unique](./arazzo/workflowId-unique.md) + +### Spot + +- [no-criteria-xpath](./spot/no-criteria-xpath.md) +- [parameters-not-in-body](./spot/parameters-not-in-body.md) +- [version-enum](./spot/version-enum.md) +- [no-actions-type-end](./spot/no-actions-type-end.test.md) + + + ## Rule configuration syntax To change your settings for any given rule, add or modify its corresponding entry in your Redocly configuration file. diff --git a/docs/rules/required-string-property-missing-min-length.md b/docs/rules/required-string-property-missing-min-length.md index 531eb284f..f539d37e2 100644 --- a/docs/rules/required-string-property-missing-min-length.md +++ b/docs/rules/required-string-property-missing-min-length.md @@ -19,7 +19,7 @@ The `minLength` keyword constrains string values. When a property of type `strin ## Configuration To configure the rule, add it to the `rules` object in your configuration file. -Set the desired [severity](/docs/cli/rules.md#severity-settings) for the rule. +Set the desired [severity](../rules.md#severity-settings) for the rule. ```yaml rules: diff --git a/docs/rules/scalar-property-missing-example.md b/docs/rules/scalar-property-missing-example.md index 4fdbc1730..561391f63 100644 --- a/docs/rules/scalar-property-missing-example.md +++ b/docs/rules/scalar-property-missing-example.md @@ -22,7 +22,7 @@ Providing examples for properties in your API description not only improves the ## Configuration To configure the rule, add it to the `rules` object in your configuration file. -Set the desired [severity](/docs/cli/rules.md#severity-settings) for the rule. +Set the desired [severity](../rules.md#severity-settings) for the rule. ```yaml rules: diff --git a/docs/rules/spec-strict-refs.md b/docs/rules/spec-strict-refs.md index 790e8fcbc..2fc28288c 100644 --- a/docs/rules/spec-strict-refs.md +++ b/docs/rules/spec-strict-refs.md @@ -36,7 +36,7 @@ The following is a list of elements the `$ref` can be used with according to the ## Configuration To configure the rule, add it to the `rules` object in your configuration file, and -set the desired [severity](/docs/cli/rules.md#severity-settings). +set the desired [severity](../rules.md#severity-settings). | Option | Type | Description | | -------- | ------ | ---------------------------------------------------------------------------------------- | diff --git a/docs/rules/tag-description.md b/docs/rules/tag-description.md index c5bbe80c6..33586d774 100644 --- a/docs/rules/tag-description.md +++ b/docs/rules/tag-description.md @@ -41,7 +41,7 @@ Remember folks, we use docs-as-code to write the docs, but the docs are the prod ## Configuration To configure the rule, add it to the `rules` object in your configuration file. -Set the desired [severity](/docs/cli/rules.md#severity-settings) for the rule. +Set the desired [severity](../rules.md#severity-settings) for the rule. ```yaml rules: From 85f99fd2eab96f0cc897a60536a146af0310f161 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 4 Oct 2024 14:36:10 +0100 Subject: [PATCH 10/23] docs: expand on the rules configuration options for basic/configured/per-api/per-format sections with examples --- docs/rules/built-in-rules.md | 91 +++++++++++++++++++++++++++--------- 1 file changed, 70 insertions(+), 21 deletions(-) diff --git a/docs/rules/built-in-rules.md b/docs/rules/built-in-rules.md index 6bf28eab1..ed0f54ca2 100644 --- a/docs/rules/built-in-rules.md +++ b/docs/rules/built-in-rules.md @@ -13,7 +13,7 @@ The _Special rules_ group contains rules that may apply to multiple objects or t Build [configurable rules](./configurable-rules.md) if the rule you need isn't listed. {% /admonition %} -## Per-format rules +## Rules for each API description format Redocly CLI can lint multiple API description formats: @@ -132,43 +132,92 @@ Within the Arazzo family of rules, there are rules for the main Arazzo specifica -## Rule configuration syntax +## Configure rules in `redocly.yaml` To change your settings for any given rule, add or modify its corresponding entry in your Redocly configuration file. -You can specify global settings in the top-level `rules` object, or use per-API settings by adding a `rules` object under each API in `apis`. +The following example shows rules configured in `redocly.yaml` with short syntax using the format `rule-name: {severity}`, where `{severity}` is one of `error`, `warn` or `off`: -You can format each entry in the `rules` object in one of the following ways: +```yaml +rules: + operation-operationId: warn + +``` -- Short syntax with single-line configuration `rule-name: {severity}`, where `{severity}` is one of `error`, `warn` or `off`. You can't configure additional rule options with this syntax. +Some rules support additional configuration options. The following example shows the more verbose format where the `severity` setting is added alongside other settings: ```yaml -apis: - main: - root: ./openapi/openapi.yaml - rules: - specific-api-rule: warn rules: - example-rule-name: error + path-excludes-patterns: + severity: error + patterns: + - ^\/fetch + - ^\/v[0-9] ``` -- Verbose syntax, where you can configure additional options for rules that support them. +Check the documentation for each rule to see if it supports additional configuration. + +### Per-API configuration + +You can set different rules for different APIs by adding a `rules` object under each API in `apis`. ```yaml +rules: + operation-operationId: error + apis: - main: - root: ./openapi/openapi.yaml + museum: + root: ./apis/museum.yaml rules: - specific-api-rule: - severity: warn + info-license: warn + tickets@beta: + root: ./apis/tickets.yaml + rules: + info-license: error + operation-operationId-url-safe: error + operation-operationId-unique: error + +``` + +Each API picks up the settings that relate to it and gets linted accordingly. + +### Per-format configuration + +To configure rules that are different for different API formats or versions of API formats, you can use the format/version-specific configuration keys as shown in the table below: + +| Configuration | Use for | +|-------|-------| +| `oas2Rules` | OpenAPI 2.x | +| `oas3_0Rules` | OpenAPI 3.0 | +| `oas3_1Rules` | OpenAPI 3.1 | +| `async2Rules` | AsyncAPI 2.6 | +| `async3Rules` | AsyncAPI 3.0 | +| `arazzoRules` | Arazzo 1.0 | + +Using this approach is useful where you have different requirements for the different types of API description, but not necessarily every API. For example, you might choose to enable a very minimal set of rules for all formats, and add some additional restrictions for the OpenAPI 3.1 descriptions since those are expected to meet a higher standard. + +The following configuration file shows an example of a minimal ruleset configuration, with some rules adjusted (both increased in severity and disabled) for different OpenAPI description formats: + +```yaml +extends: + - minimal + rules: - example-rule-name: - severity: error - rule-option-one: value - rule-option-two: value + info-description: warn + +oas2Rules: + no-unresolved-refs: off + +oas3_1Rules: + info-license: error + no-ambiguous-paths: error + operation-operationId-unique: error ``` -## Next steps +Use these settings alongside `rules` configuration to tune the linting for each API description format. + +## Resources - Learn more about [API linting](../api-standards.md), or follow the [guide to configuring a ruleset](../guides/configure-rules.md). +- Visit the [documentation on per-API configuration](../configuration/apis.md) - If you didn't find the rule you need, build a [configurable rule](./configurable-rules.md) for a perfect linting fit. From f8a7bc282550052e3548acdcc23f42d52e5bf402 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 4 Oct 2024 14:45:14 +0100 Subject: [PATCH 11/23] docs: add descriptions and sorting to the new format rules --- docs/rules/built-in-rules.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/docs/rules/built-in-rules.md b/docs/rules/built-in-rules.md index ed0f54ca2..196d20556 100644 --- a/docs/rules/built-in-rules.md +++ b/docs/rules/built-in-rules.md @@ -103,8 +103,11 @@ The rules list is split into sections. ## AsyncAPI rules -- [no-channel-trailing-slash](./async/no-channel-trailing-slash.md) -- [channels-kebab-case](./async/channels-kebab-case.md) +Use the rules in this section for AsyncAPI-specific linting. +Other rules such as the `spec` and `info.*` rules also apply to AsyncAPI. + +- [channels-kebab-case](./async/channels-kebab-case.md): Channels must be in `kebab-case` format +- [no-channel-trailing-slash](./async/no-channel-trailing-slash.md): No trailing slashes on channels ## Arazzo rules @@ -112,23 +115,23 @@ Within the Arazzo family of rules, there are rules for the main Arazzo specifica ### Arazzo -- [parameters-unique](./arazzo/parameters-unique.md) -- [step-onSuccess-unique](./arazzo/step-onSuccess-unique.md) -- [workflow-dependsOn](./arazzo/workflow-dependsOn.md) -- [sourceDescriptions-type](./arazzo/sourceDescriptions-type.md) -- [step-onFailure-unique](./arazzo/step-onFailure-unique.md) -- [sourceDescriptions-name-unique](./arazzo/sourceDescriptions-name-unique.md) -- [stepId-unique](./arazzo/stepId-unique.md) -- [criteria-unique](./arazzo/criteria-unique.md) -- [requestBody-replacements-unique](./arazzo/requestBody-replacements-unique.md) -- [workflowId-unique](./arazzo/workflowId-unique.md) +- [criteria-unique](./arazzo/criteria-unique.md): the criteria list must not contain duplicated assertions +- [parameters-unique](./arazzo/parameters-unique.md): the `parameters` list must not include duplicate parameters +- [requestBody-replacements-unique](./arazzo/requestBody-replacements-unique.md): the `replacements` of the `requestBody` object must be unique +- [sourceDescriptions-name-unique](./arazzo/sourceDescriptions-name-unique.md): the `name` property of the `sourceDescription` object must be unique across all source descriptions +- [sourceDescriptions-type](./arazzo/sourceDescriptions-type.md): the `type` property of the `sourceDescription` object must be either `openapi` or `arazzo` +- [stepId-unique](./arazzo/stepId-unique.md): the `stepId` must be unique amongst all steps described in the workflow +- [step-onFailure-unique](./arazzo/step-onFailure-unique.md): the `onFailure` actions of the `step` object must be unique +- [step-onSuccess-unique](./arazzo/step-onSuccess-unique.md): the `onSuccess` actions of the `step` object must be unique +- [workflow-dependsOn](./arazzo/workflow-dependsOn.md): the items in the `workflow` `dependsOn` property must exist and be unique +- [workflowId-unique](./arazzo/workflowId-unique.md): the `workflowId` property must be unique across all workflows ### Spot -- [no-criteria-xpath](./spot/no-criteria-xpath.md) -- [parameters-not-in-body](./spot/parameters-not-in-body.md) -- [version-enum](./spot/version-enum.md) -- [no-actions-type-end](./spot/no-actions-type-end.test.md) +- [no-actions-type-end](./spot/no-actions-type-end.test.md): the `end` type action is not supported by Spot. +- [no-criteria-xpath](./spot/no-criteria-xpath.md): the `xpath` type criteria is not supported by Spot. +- [parameters-not-in-body](./spot/parameters-not-in-body.md): the `in` section inside `parameters` must not contain a `body`. +- [version-enum](./spot/version-enum.md): the `version` property must be one of the supported values. From 988785a27430cb337854b72ec4527c5410ec1e7e Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 4 Oct 2024 15:11:14 +0100 Subject: [PATCH 12/23] docs: Split rules config to separate page, add missing rules to list, refactor sidebar --- docs/rules/built-in-rules.md | 89 ++------------------------------ docs/rules/configure-rules.md | 96 +++++++++++++++++++++++++++++++++++ docs/sidebars.yaml | 7 ++- 3 files changed, 105 insertions(+), 87 deletions(-) create mode 100644 docs/rules/configure-rules.md diff --git a/docs/rules/built-in-rules.md b/docs/rules/built-in-rules.md index 196d20556..49a69d454 100644 --- a/docs/rules/built-in-rules.md +++ b/docs/rules/built-in-rules.md @@ -55,6 +55,7 @@ The rules list is split into sections. ### Parameters +- [array-parameter-serialization](./array-parameter-serialization.md): Require `style` and `explode` for parameters with array type - [boolean-parameter-prefixes](./boolean-parameter-prefixes.md): All boolean paramater names start with a particular prefix (such as "is") - [no-invalid-parameter-examples](./no-invalid-parameter-examples.md): Parameter examples must match declared schema types - [operation-parameters-unique](./operation-parameters-unique.md): No repeated parameter names within an operation @@ -75,10 +76,12 @@ The rules list is split into sections. ### Requests, Responses, and Schemas +- [component-name-unique](./component-name-unique.md): Check for schema-wide unqiue naming of parameters, schemas, request bodies and responses - [no-enum-type-mismatch](./no-enum-type-mismatch.md): Enum options must match the data type declared in the schema - [no-example-value-and-externalValue](./no-example-value-and-externalValue.md): Either the `value` or `externalValue` may be present, but not both - [no-invalid-media-type-examples](./no-invalid-media-type-examples.md): Example request bodies must match the declared schema - [no-invalid-schema-examples](./no-invalid-schema-examples.md): Schema examples must match declared types +- [no-required-schema-properties-undefined](./no-required-schema-properties-undefined.md): All properties marked as required must be defined - [request-mime-type](./request-mime-type.md): Configure allowed mime types for requests - [response-mime-type](./response-mime-type.md): Configure allowed mime types for responses - [response-contains-header](./response-contains-header.md): List headers that must be included with specific response types @@ -133,92 +136,6 @@ Within the Arazzo family of rules, there are rules for the main Arazzo specifica - [parameters-not-in-body](./spot/parameters-not-in-body.md): the `in` section inside `parameters` must not contain a `body`. - [version-enum](./spot/version-enum.md): the `version` property must be one of the supported values. - - -## Configure rules in `redocly.yaml` - -To change your settings for any given rule, add or modify its corresponding entry in your Redocly configuration file. - -The following example shows rules configured in `redocly.yaml` with short syntax using the format `rule-name: {severity}`, where `{severity}` is one of `error`, `warn` or `off`: - -```yaml -rules: - operation-operationId: warn - -``` - -Some rules support additional configuration options. The following example shows the more verbose format where the `severity` setting is added alongside other settings: - -```yaml -rules: - path-excludes-patterns: - severity: error - patterns: - - ^\/fetch - - ^\/v[0-9] -``` - -Check the documentation for each rule to see if it supports additional configuration. - -### Per-API configuration - -You can set different rules for different APIs by adding a `rules` object under each API in `apis`. - -```yaml -rules: - operation-operationId: error - -apis: - museum: - root: ./apis/museum.yaml - rules: - info-license: warn - tickets@beta: - root: ./apis/tickets.yaml - rules: - info-license: error - operation-operationId-url-safe: error - operation-operationId-unique: error - -``` - -Each API picks up the settings that relate to it and gets linted accordingly. - -### Per-format configuration - -To configure rules that are different for different API formats or versions of API formats, you can use the format/version-specific configuration keys as shown in the table below: - -| Configuration | Use for | -|-------|-------| -| `oas2Rules` | OpenAPI 2.x | -| `oas3_0Rules` | OpenAPI 3.0 | -| `oas3_1Rules` | OpenAPI 3.1 | -| `async2Rules` | AsyncAPI 2.6 | -| `async3Rules` | AsyncAPI 3.0 | -| `arazzoRules` | Arazzo 1.0 | - -Using this approach is useful where you have different requirements for the different types of API description, but not necessarily every API. For example, you might choose to enable a very minimal set of rules for all formats, and add some additional restrictions for the OpenAPI 3.1 descriptions since those are expected to meet a higher standard. - -The following configuration file shows an example of a minimal ruleset configuration, with some rules adjusted (both increased in severity and disabled) for different OpenAPI description formats: - -```yaml -extends: - - minimal - -rules: - info-description: warn - -oas2Rules: - no-unresolved-refs: off - -oas3_1Rules: - info-license: error - no-ambiguous-paths: error - operation-operationId-unique: error -``` - -Use these settings alongside `rules` configuration to tune the linting for each API description format. - ## Resources - Learn more about [API linting](../api-standards.md), or follow the [guide to configuring a ruleset](../guides/configure-rules.md). diff --git a/docs/rules/configure-rules.md b/docs/rules/configure-rules.md new file mode 100644 index 000000000..f8a9024ec --- /dev/null +++ b/docs/rules/configure-rules.md @@ -0,0 +1,96 @@ +# Configure linting rules + +Configure the rules for API linting in the `redocly.yaml` configuration file. + +You can add rules, change their severity, or turn them off completely. +Some rules support additional configuration. + +You can also provide per-format or even per-API rule configuration. +Use these approaches when your different types of API, or individual APIs, have different linting requirements. + +## Simple rule configuration + +The following example shows rules configured in `redocly.yaml` with short syntax using the format `rule-name: {severity}`, where `{severity}` is one of `error`, `warn` or `off`: + +```yaml +rules: + operation-operationId: warn + +``` + +Some rules support additional configuration options. The following example shows the more verbose format where the `severity` setting is added alongside other settings: + +```yaml +rules: + path-excludes-patterns: + severity: error + patterns: + - ^\/fetch + - ^\/v[0-9] +``` + +Check the documentation for each rule to see if it supports additional configuration. + +## Per-format configuration + +To configure rules that are different for different API formats or versions of API formats, you can use the format/version-specific configuration keys as shown in the table below: + +| Configuration | Use for | +|-------|-------| +| `oas2Rules` | OpenAPI 2.x | +| `oas3_0Rules` | OpenAPI 3.0 | +| `oas3_1Rules` | OpenAPI 3.1 | +| `async2Rules` | AsyncAPI 2.6 | +| `async3Rules` | AsyncAPI 3.0 | +| `arazzoRules` | Arazzo 1.0 | + +Using this approach is useful where you have different requirements for the different types of API description, but not necessarily every API. For example, you might choose to enable a very minimal set of rules for all formats, and add some additional restrictions for the OpenAPI 3.1 descriptions since those are expected to meet a higher standard. + +The following configuration file shows an example of a minimal ruleset configuration, with some rules adjusted (both increased in severity and disabled) for different OpenAPI description formats: + +```yaml +extends: + - minimal + +rules: + info-description: warn + +oas2Rules: + no-unresolved-refs: off + +oas3_1Rules: + info-license: error + no-ambiguous-paths: error + operation-operationId-unique: error +``` + +Use these settings alongside `rules` configuration to tune the linting for each API description format. + +## Per-API configuration + +You can set different rules for different APIs by adding a `rules` object under each API in `apis`. + +```yaml +rules: + operation-operationId: error + +apis: + museum: + root: ./apis/museum.yaml + rules: + info-license: warn + tickets@beta: + root: ./apis/tickets.yaml + rules: + info-license: error + operation-operationId-url-safe: error + operation-operationId-unique: error + +``` + +Each API picks up the settings that relate to it and gets linted accordingly. + +## Resources + +- Learn more about [rules and rulesets](../rules.md). +- Check the list of [built-in rules](./built-in-rules.md). diff --git a/docs/sidebars.yaml b/docs/sidebars.yaml index 6fd99ac47..4761e654d 100644 --- a/docs/sidebars.yaml +++ b/docs/sidebars.yaml @@ -71,7 +71,10 @@ page: api-standards.md items: - page: rules.md - label: Rules + group: Rules and rulesets + items: + - page: rules/recommended.md + - page: rules/minimal.md - group: Built-in rules page: rules/built-in-rules.md items: @@ -127,6 +130,8 @@ - page: rules/spec-strict-refs.md - page: rules/tag-description.md - page: rules/tags-alphabetical.md + - page: rules/configure-rules.md + label: Rule configuration - page: rules/configurable-rules.md - group: Decorators page: decorators.md From 5cf1a5858a8e45d3c22b28c0e8752c2855ecad69 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 4 Oct 2024 18:03:10 +0100 Subject: [PATCH 13/23] docs: add copy/paste versions of ruleset configurations for each api description format --- docs/rules/minimal.md | 2 + docs/rules/recommended.md | 5 + docs/rules/ruleset-templates.md | 520 ++++++++++++++++++++++++++++++++ docs/sidebars.yaml | 1 + 4 files changed, 528 insertions(+) create mode 100644 docs/rules/ruleset-templates.md diff --git a/docs/rules/minimal.md b/docs/rules/minimal.md index 78ad2fdd3..6a651a60a 100644 --- a/docs/rules/minimal.md +++ b/docs/rules/minimal.md @@ -37,3 +37,5 @@ Warnings: - [spec-components-invalid-map-name](./spec-components-invalid-map-name.md) - [tag-description](./tag-description.md) - [version-enum](./spot/version-enum.md) + +A copy/pastable version of this ruleset is available as a [ruleset template](./ruleset-templates.md). diff --git a/docs/rules/recommended.md b/docs/rules/recommended.md index c6d3b69f4..aedf644e9 100644 --- a/docs/rules/recommended.md +++ b/docs/rules/recommended.md @@ -52,3 +52,8 @@ Warnings: ## Recommended strict ruleset There is also a `recommended-strict` version of `recommended`, which elevates all warnings to errors. + +## Ruleset template + +A copy/pastable version of this ruleset is available as a [ruleset template](./ruleset-templates.md). + diff --git a/docs/rules/ruleset-templates.md b/docs/rules/ruleset-templates.md new file mode 100644 index 000000000..b6d676e7d --- /dev/null +++ b/docs/rules/ruleset-templates.md @@ -0,0 +1,520 @@ +# Ruleset templates + +Redocly CLI includes some default rulesets to get you started quickly. + +To edit/adjust the rules you use in your own projects, [configure your rules](./configure-rules.md) accordingly to override any settings from the original ruleset. + +On this page, each ruleset is included for each of the supported API description formats. +You can use this information for your own reference, or copy/paste them in order to use separate configuration for each API format. +Consult the relevant section below, each code sample is formatted to be included in `redocly.yaml` directly. + +More information and examples for individual rules can be found in the [built-in rules documentation](./built-in-rules.md). + +## Minimal rulesets + +The minimal rulesets are a decent baseline that you can use to selective enable more rules or extend rulesets from. + +### Minimal ruleset: OpenAPI 3.1 + +```yaml +oas3_1Rules: + info-contact: off + info-license: off + info-license-url: off + info-license-strict: off + tag-description: warn + tags-alphabetical: off + parameter-description: off + no-path-trailing-slash: warn + no-identical-paths: warn + no-ambiguous-paths: warn + path-declaration-must-exist: warn + path-not-include-query: warn + path-parameters-defined: warn + operation-description: off + operation-2xx-response: warn + operation-4xx-response: off + operation-operationId: warn + operation-summary: warn + operation-operationId-unique: warn + operation-parameters-unique: warn + operation-tag-defined: off + security-defined: warn + operation-operationId-url-safe: warn + operation-singular-tag: off + no-unresolved-refs: error + no-enum-type-mismatch: warn + paths-kebab-case: off + spec: error + spec-strict-refs: off + no-http-verbs-in-paths: off + no-invalid-parameter-examples: off + no-invalid-schema-examples: off + path-excludes-patterns: off + path-http-verbs-order: off + path-params-defined: off + required-string-property-missing-min-length: off + response-contains-header: off + path-segment-plural: off + scalar-property-missing-example: off + no-required-schema-properties-undefined: off + no-invalid-media-type-examples: warn + no-server-example.com: warn + no-server-trailing-slash: error + no-empty-servers: warn + no-example-value-and-externalValue: warn + no-unused-components: warn + no-undefined-server-variable: warn + no-server-variables-empty-enum: error + spec-components-invalid-map-name: warn + boolean-parameter-prefixes: off + component-name-unique: off + operation-4xx-problem-details-rfc7807: off + request-mime-type: off + response-contains-property: off + response-mime-type: off + array-parameter-serialization: off +``` + +### Minimal ruleset: OpenAPI 3.0 + +```yaml +oas3_0Rules: + info-contact: off + info-license: off + info-license-url: off + info-license-strict: off + tag-description: warn + tags-alphabetical: off + parameter-description: off + no-path-trailing-slash: warn + no-identical-paths: warn + no-ambiguous-paths: warn + path-declaration-must-exist: warn + path-not-include-query: warn + path-parameters-defined: warn + operation-description: off + operation-2xx-response: warn + operation-4xx-response: off + operation-operationId: warn + operation-summary: warn + operation-operationId-unique: warn + operation-parameters-unique: warn + operation-tag-defined: off + security-defined: warn + operation-operationId-url-safe: warn + operation-singular-tag: off + no-unresolved-refs: error + no-enum-type-mismatch: warn + paths-kebab-case: off + spec: error + spec-strict-refs: off + no-http-verbs-in-paths: off + no-invalid-parameter-examples: off + no-invalid-schema-examples: off + path-excludes-patterns: off + path-http-verbs-order: off + path-params-defined: off + required-string-property-missing-min-length: off + response-contains-header: off + path-segment-plural: off + scalar-property-missing-example: off + no-required-schema-properties-undefined: off + no-invalid-media-type-examples: warn + no-server-example.com: warn + no-server-trailing-slash: error + no-empty-servers: warn + no-example-value-and-externalValue: warn + no-unused-components: warn + no-undefined-server-variable: warn + no-server-variables-empty-enum: error + spec-components-invalid-map-name: warn + boolean-parameter-prefixes: off + component-name-unique: off + operation-4xx-problem-details-rfc7807: off + request-mime-type: off + response-contains-property: off + response-mime-type: off + array-parameter-serialization: off +``` + +### Minimal ruleset: OpenAPI 2.0 + +```yaml +oas2Rules: + info-contact: off + info-license: off + info-license-url: off + info-license-strict: off + tag-description: warn + tags-alphabetical: off + parameter-description: off + no-path-trailing-slash: warn + no-identical-paths: warn + no-ambiguous-paths: warn + path-declaration-must-exist: warn + path-not-include-query: warn + path-parameters-defined: warn + operation-description: off + operation-2xx-response: warn + operation-4xx-response: off + operation-operationId: warn + operation-summary: warn + operation-operationId-unique: warn + operation-parameters-unique: warn + operation-tag-defined: off + security-defined: warn + operation-operationId-url-safe: warn + operation-singular-tag: off + no-unresolved-refs: error + no-enum-type-mismatch: warn + paths-kebab-case: off + spec: error + spec-strict-refs: off + no-http-verbs-in-paths: off + no-invalid-parameter-examples: off + no-invalid-schema-examples: off + path-excludes-patterns: off + path-http-verbs-order: off + path-params-defined: off + required-string-property-missing-min-length: off + response-contains-header: off + path-segment-plural: off + scalar-property-missing-example: off + no-required-schema-properties-undefined: off + boolean-parameter-prefixes: off + request-mime-type: off + response-contains-property: off + response-mime-type: off +``` +### Minimal ruleset: AsyncAPI 3.0 + +```yaml +async3Rules: + spec: error + info-contact: off + info-license-strict: off + operation-operationId: warn + tag-description: warn + tags-alphabetical: off + channels-kebab-case: off + no-channel-trailing-slash: off +``` + +### Minimal ruleset: AsyncAPI 2.6 + +```yaml +async2Rules: + spec: error + info-contact: off + info-license-strict: off + operation-operationId: warn + tag-description: warn + tags-alphabetical: off + channels-kebab-case: off + no-channel-trailing-slash: off +``` + +### Minimal ruleset: Arazzo 1.0 + +```yaml +arazzoRules: + spec: error + parameters-not-in-body: off + sourceDescription-type: off + version-enum: warn + workflowId-unique: error + stepId-unique: error + sourceDescription-name-unique: off + workflow-dependsOn: off + parameters-unique: off + step-onSuccess-unique: off + step-onFailure-unique: off + requestBody-replacements-unique: off + no-criteria-xpath: off + no-actions-type-end: off + criteria-unique: off +``` + +## Recommended rulesets + +The default behavior is to use a recommended ruleset. +The recommended rulesets for each format are listed below. +There is also a "recommended-strict" ruleset which is identical but with all `warn` settings changed to `error`. + +### Recommended ruleset: OpenAPI 3.1 + +```yaml +rules: + info-contact: off + info-license: warn + info-license-url: off + info-license-strict: warn + tag-description: warn + tags-alphabetical: off + parameter-description: off + no-path-trailing-slash: error + no-identical-paths: error + no-ambiguous-paths: warn + path-declaration-must-exist: error + path-not-include-query: error + path-parameters-defined: error + operation-description: off + operation-2xx-response: warn + operation-4xx-response: warn + operation-operationId: warn + operation-summary: error + operation-operationId-unique: error + operation-operationId-url-safe: error + operation-parameters-unique: error + operation-tag-defined: off + security-defined: error + operation-singular-tag: off + no-unresolved-refs: error + no-enum-type-mismatch: error + paths-kebab-case: off + spec: error + spec-strict-refs: off + no-http-verbs-in-paths: off + no-invalid-parameter-examples: off + no-invalid-schema-examples: off + path-excludes-patterns: off + path-http-verbs-order: off + path-params-defined: off + path-segment-plural: off + required-string-property-missing-min-length: off + response-contains-header: off + scalar-property-missing-example: off + no-required-schema-properties-undefined: off + +oas3_1Rules: + info-contact: off + info-license: warn + info-license-url: off + info-license-strict: warn + tag-description: warn + tags-alphabetical: off + parameter-description: off + no-path-trailing-slash: error + no-identical-paths: error + no-ambiguous-paths: warn + path-declaration-must-exist: error + path-not-include-query: error + path-parameters-defined: error + operation-description: off + operation-2xx-response: warn + operation-4xx-response: warn + operation-operationId: warn + operation-summary: error + operation-operationId-unique: error + operation-operationId-url-safe: error + operation-parameters-unique: error + operation-tag-defined: off + security-defined: error + operation-singular-tag: off + no-unresolved-refs: error + no-enum-type-mismatch: error + paths-kebab-case: off + spec: error + spec-strict-refs: off + no-http-verbs-in-paths: off + no-invalid-parameter-examples: off + no-invalid-schema-examples: off + path-excludes-patterns: off + path-http-verbs-order: off + path-params-defined: off + path-segment-plural: off + required-string-property-missing-min-length: off + response-contains-header: off + scalar-property-missing-example: off + no-required-schema-properties-undefined: off + no-invalid-media-type-examples: warn + no-server-example.com: warn + no-server-trailing-slash: error + no-empty-servers: error + no-example-value-and-externalValue: error + no-unused-components: warn + no-undefined-server-variable: error + no-server-variables-empty-enum: error + spec-components-invalid-map-name: error + boolean-parameter-prefixes: off + component-name-unique: off + operation-4xx-problem-details-rfc7807: off + request-mime-type: off + response-contains-property: off + response-mime-type: off + array-parameter-serialization: off +``` + +### Recommended ruleset: OpenAPI 3.0 + +```yaml +oas3_0Rules: + info-contact: off + info-license: warn + info-license-url: off + info-license-strict: warn + tag-description: warn + tags-alphabetical: off + parameter-description: off + no-path-trailing-slash: error + no-identical-paths: error + no-ambiguous-paths: warn + path-declaration-must-exist: error + path-not-include-query: error + path-parameters-defined: error + operation-description: off + operation-2xx-response: warn + operation-4xx-response: warn + operation-operationId: warn + operation-summary: error + operation-operationId-unique: error + operation-operationId-url-safe: error + operation-parameters-unique: error + operation-tag-defined: off + security-defined: error + operation-singular-tag: off + no-unresolved-refs: error + no-enum-type-mismatch: error + paths-kebab-case: off + spec: error + spec-strict-refs: off + no-http-verbs-in-paths: off + no-invalid-parameter-examples: off + no-invalid-schema-examples: off + path-excludes-patterns: off + path-http-verbs-order: off + path-params-defined: off + path-segment-plural: off + required-string-property-missing-min-length: off + response-contains-header: off + scalar-property-missing-example: off + no-required-schema-properties-undefined: off + no-invalid-media-type-examples: warn + no-server-example.com: warn + no-server-trailing-slash: error + no-empty-servers: error + no-example-value-and-externalValue: error + no-unused-components: warn + no-undefined-server-variable: error + no-server-variables-empty-enum: error + spec-components-invalid-map-name: error + boolean-parameter-prefixes: off + component-name-unique: off + operation-4xx-problem-details-rfc7807: off + request-mime-type: off + response-contains-property: off + response-mime-type: off + array-parameter-serialization: off +``` + +### Recommended ruleset: OpenAPI 2.0 + +```yaml +oas2Rules: + info-contact: off + info-license: warn + info-license-url: off + info-license-strict: warn + tag-description: warn + tags-alphabetical: off + parameter-description: off + no-path-trailing-slash: error + no-identical-paths: error + no-ambiguous-paths: warn + path-declaration-must-exist: error + path-not-include-query: error + path-parameters-defined: error + operation-description: off + operation-2xx-response: warn + operation-4xx-response: warn + operation-operationId: warn + operation-summary: error + operation-operationId-unique: error + operation-operationId-url-safe: error + operation-parameters-unique: error + operation-tag-defined: off + security-defined: error + operation-singular-tag: off + no-unresolved-refs: error + no-enum-type-mismatch: error + paths-kebab-case: off + spec: error + spec-strict-refs: off + no-http-verbs-in-paths: off + no-invalid-parameter-examples: off + no-invalid-schema-examples: off + path-excludes-patterns: off + path-http-verbs-order: off + path-params-defined: off + path-segment-plural: off + required-string-property-missing-min-length: off + response-contains-header: off + scalar-property-missing-example: off + no-required-schema-properties-undefined: off + boolean-parameter-prefixes: off + request-mime-type: off + response-contains-property: off + response-mime-type: off +``` + +### Recommended ruleset: AsyncAPI 3.0 + +```yaml +async3Rules: + spec: error + info-contact: off + info-license-strict: warn + operation-operationId: warn + tag-description: warn + tags-alphabetical: off + channels-kebab-case: off + no-channel-trailing-slash: off +``` + +### Recommended ruleset: AsyncAPI 2.6 + +```yaml +async2Rules: + spec: error + info-contact: off + info-license-strict: warn + operation-operationId: warn + tag-description: warn + tags-alphabetical: off + channels-kebab-case: off + no-channel-trailing-slash: off +``` + +### Recommended ruleset: Arazzo 1.0 + +```yaml +arazzoRules: + spec: error + parameters-not-in-body: warn + sourceDescription-type: error + version-enum: warn + workflowId-unique: error + stepId-unique: error + sourceDescription-name-unique: error + workflow-dependsOn: error + parameters-unique: error + step-onSuccess-unique: warn + step-onFailure-unique: warn + requestBody-replacements-unique: warn + no-criteria-xpath: warn + no-actions-type-end: warn + criteria-unique: warn +``` + +## Resources + +- Learn about [API governance](../api-standards.md). +- More information and examples for individual rules can be found in the [built-in rules documentation](./built-in-rules.md). +- Add your own [configurable rules](./configurable-rules.md) if there's anything you need that isn't already provided as a built in rule. + + + + + + diff --git a/docs/sidebars.yaml b/docs/sidebars.yaml index 4761e654d..6e12b8829 100644 --- a/docs/sidebars.yaml +++ b/docs/sidebars.yaml @@ -75,6 +75,7 @@ items: - page: rules/recommended.md - page: rules/minimal.md + - page: rules/ruleset-templates.md - group: Built-in rules page: rules/built-in-rules.md items: From 5ca82e9b3093d2094726e5df3c1237a89ea4b52e Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 4 Oct 2024 18:12:30 +0100 Subject: [PATCH 14/23] docs: fix a renamed rule and a stray ARAZZO label --- docs/guides/lint-arazzo.md | 19 ++----------------- docs/rules/arazzo/workflow-dependsOn.md | 2 +- 2 files changed, 3 insertions(+), 18 deletions(-) diff --git a/docs/guides/lint-arazzo.md b/docs/guides/lint-arazzo.md index 1efa1e22c..a5ea1503a 100644 --- a/docs/guides/lint-arazzo.md +++ b/docs/guides/lint-arazzo.md @@ -71,22 +71,7 @@ run `redocly lint --generate-ignore-file` to add all problems to the ignore file ## Configure the linting rules Choose from the ready-made rulesets (`minimal`, `recommended` or `recommended-strict`), or go one better and configure the rules that suit your use case. -The rules available for linting Arazzo are: - -- `parameters-not-in-body`: the `in` section inside `parameters` must not contain a `body`. -- `sourceDescription-type`: the `type` property of the `sourceDescription` object must be either `openapi` or `arazzo`. -- `version-enum`: the `version` property must be one of the supported values. -- `workflowId-unique`: the `workflowId` property must be unique across all workflows. -- `stepId-unique`: the `stepId` must be unique amongst all steps described in the workflow. -- `sourceDescription-name-unique`: the `name` property of the `sourceDescription` object must be unique across all source descriptions. -- `workflow-dependsOn`: the items in the `workflow` `dependsOn` property must exist and be unique. -- `parameters-unique`: the `parameters` list must not include duplicate parameters. -- `step-onSuccess-unique`: the `onSuccess` actions of the `step` object must be unique. -- `step-onFailure-unique`: the `onFailure` actions of the `step` object must be unique. -- `requestBody-replacements-unique`: the `replacements` of the `requestBody` object must be unique. -- `no-criteria-xpath`: the `xpath` type criteria is not supported by Spot. -- `no-actions-type-end`: the `end` type action is not supported by Spot. -- `criteria-unique`: the criteria list must not contain duplicated assertions. +There's a full [list of built-in rules for Arazzo](../rules/built-in-rules.md#arazzo-rules) to refer to. Add the rules to `redocly.yaml`, but for Arazzo specifications, the rules go in their own configuration section called `arazzoRules`. The following example shows configuration for the minimal ruleset with some additional rules configuration: @@ -96,7 +81,7 @@ extends: - minimal arazzoRules: - sourceDescription-name-unique: warn + sourceDescriptions-name-unique: warn version-enum: error ``` diff --git a/docs/rules/arazzo/workflow-dependsOn.md b/docs/rules/arazzo/workflow-dependsOn.md index 558e3b7c4..ae96a7ee2 100644 --- a/docs/rules/arazzo/workflow-dependsOn.md +++ b/docs/rules/arazzo/workflow-dependsOn.md @@ -2,7 +2,7 @@ Requires the items in the `workflow` `dependsOn` property to exist and to be unique. -| ARAZZO | Compatibility | +| Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | From 8478eaca576ab412c7c872ac14eba37b67063734 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 4 Oct 2024 18:13:38 +0100 Subject: [PATCH 15/23] docs: run prettier --- docs/rules/arazzo/parameters-unique.md | 2 +- docs/rules/configure-rules.md | 16 ++++++++-------- docs/rules/recommended.md | 1 - docs/rules/ruleset-templates.md | 7 +------ docs/rules/spot/parameters-not-in-body.md | 2 +- 5 files changed, 11 insertions(+), 17 deletions(-) diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md index 6a7c90fbe..9c9663afb 100644 --- a/docs/rules/arazzo/parameters-unique.md +++ b/docs/rules/arazzo/parameters-unique.md @@ -9,7 +9,7 @@ Requires unique values in the `parameters` lists. ## API design principles A list of `parameters` that are applicable to a step or all the steps described in a workflow should not contain duplicates. -If duplicates are present, unexpected parameter overrides could cause problems. +If duplicates are present, unexpected parameter overrides could cause problems. Checks parameter lists in the following locations: diff --git a/docs/rules/configure-rules.md b/docs/rules/configure-rules.md index f8a9024ec..cc731b168 100644 --- a/docs/rules/configure-rules.md +++ b/docs/rules/configure-rules.md @@ -15,14 +15,14 @@ The following example shows rules configured in `redocly.yaml` with short syntax ```yaml rules: operation-operationId: warn - + ``` Some rules support additional configuration options. The following example shows the more verbose format where the `severity` setting is added alongside other settings: ```yaml rules: - path-excludes-patterns: + path-excludes-patterns: severity: error patterns: - ^\/fetch @@ -35,14 +35,14 @@ Check the documentation for each rule to see if it supports additional configura To configure rules that are different for different API formats or versions of API formats, you can use the format/version-specific configuration keys as shown in the table below: -| Configuration | Use for | -|-------|-------| -| `oas2Rules` | OpenAPI 2.x | -| `oas3_0Rules` | OpenAPI 3.0 | -| `oas3_1Rules` | OpenAPI 3.1 | +| Configuration | Use for | +| ------------- | ------------ | +| `oas2Rules` | OpenAPI 2.x | +| `oas3_0Rules` | OpenAPI 3.0 | +| `oas3_1Rules` | OpenAPI 3.1 | | `async2Rules` | AsyncAPI 2.6 | | `async3Rules` | AsyncAPI 3.0 | -| `arazzoRules` | Arazzo 1.0 | +| `arazzoRules` | Arazzo 1.0 | Using this approach is useful where you have different requirements for the different types of API description, but not necessarily every API. For example, you might choose to enable a very minimal set of rules for all formats, and add some additional restrictions for the OpenAPI 3.1 descriptions since those are expected to meet a higher standard. diff --git a/docs/rules/recommended.md b/docs/rules/recommended.md index aedf644e9..2e5d51e88 100644 --- a/docs/rules/recommended.md +++ b/docs/rules/recommended.md @@ -56,4 +56,3 @@ There is also a `recommended-strict` version of `recommended`, which elevates al ## Ruleset template A copy/pastable version of this ruleset is available as a [ruleset template](./ruleset-templates.md). - diff --git a/docs/rules/ruleset-templates.md b/docs/rules/ruleset-templates.md index b6d676e7d..32acf5e15 100644 --- a/docs/rules/ruleset-templates.md +++ b/docs/rules/ruleset-templates.md @@ -187,6 +187,7 @@ oas2Rules: response-contains-property: off response-mime-type: off ``` + ### Minimal ruleset: AsyncAPI 3.0 ```yaml @@ -512,9 +513,3 @@ arazzoRules: - Learn about [API governance](../api-standards.md). - More information and examples for individual rules can be found in the [built-in rules documentation](./built-in-rules.md). - Add your own [configurable rules](./configurable-rules.md) if there's anything you need that isn't already provided as a built in rule. - - - - - - diff --git a/docs/rules/spot/parameters-not-in-body.md b/docs/rules/spot/parameters-not-in-body.md index 12709125f..b045c6b5f 100644 --- a/docs/rules/spot/parameters-not-in-body.md +++ b/docs/rules/spot/parameters-not-in-body.md @@ -10,7 +10,7 @@ Requires the `in` section inside `parameters` must not contain a `body`. This is rule is specific to the Spot tool. `body` is not supported in the `in` section inside `parameters`. -This affects parameter lists in: +This affects parameter lists in: - `workflows.[workflow].parameters` - `workflows.[workflow[.steps.[step].parameters` From 9d18cb7e0ca74faeb347bdf641b8b8b24d8348ab Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Mon, 7 Oct 2024 09:35:15 +0100 Subject: [PATCH 16/23] docs: adjust rule example to be more obvious --- docs/rules/arazzo/parameters-unique.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md index 9c9663afb..04fbce21b 100644 --- a/docs/rules/arazzo/parameters-unique.md +++ b/docs/rules/arazzo/parameters-unique.md @@ -63,8 +63,8 @@ workflows: name: Authorization value: Basic Og== - in: header - name: Auth - value: Main Og== + name: X-Forwarded-For + value: 1.2.3.4 ``` ## Resources From ce5d903bdda4b6db86f3dfc3d32536d5950c7094 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Mon, 7 Oct 2024 09:46:05 +0100 Subject: [PATCH 17/23] docs: update link --- docs/rules/built-in-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rules/built-in-rules.md b/docs/rules/built-in-rules.md index 49a69d454..a177b0b94 100644 --- a/docs/rules/built-in-rules.md +++ b/docs/rules/built-in-rules.md @@ -4,7 +4,7 @@ slug: /docs/cli/rules/built-in-rules # Built-in rules -The built-in rules are the ones we use ourselves and think apply to the majority of APIs. Some have some additional [configuration](#rule-configuration-syntax), but otherwise all you need to do is decide whether each rule should `error`, `warn` or be `off`. +The built-in rules are the ones we use ourselves and think apply to the majority of APIs. Some have some additional [configuration](./configure-rules.md), but otherwise all you need to do is decide whether each rule should `error`, `warn` or be `off`. All the built-in rules are listed here, roughly grouped by the OpenAPI object they apply to. The _Special rules_ group contains rules that may apply to multiple objects or to the entire OpenAPI document. From 3074a8904c8efa9364576e2e3ce168cc5beb8bba Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Mon, 7 Oct 2024 11:06:44 +0100 Subject: [PATCH 18/23] docs: update AsyncAPI channel rules with more info, add all rules to sidebars --- docs/rules/async/channels-kebab-case.md | 39 ++++++++++++++----- docs/rules/async/no-channel-trailing-slash.md | 36 +++++++++++++---- docs/sidebars.yaml | 21 ++++++++++ 3 files changed, 78 insertions(+), 18 deletions(-) diff --git a/docs/rules/async/channels-kebab-case.md b/docs/rules/async/channels-kebab-case.md index cb7396e16..84be0f4b1 100644 --- a/docs/rules/async/channels-kebab-case.md +++ b/docs/rules/async/channels-kebab-case.md @@ -4,12 +4,12 @@ Channel address should be `kebab-case` (lowercase with hyphens). | AsyncAPI | Compatibility | | -------- | ------------- | -| 2.0 | ✅ | +| 2.6 | ✅ | | 3.0 | ✅ | ## API design principles -Channel address should be `kebab-case` (lowercase with hyphens). +Using consistent casing for the channel address provides a better developer experience and a more predictable experience overall. ## Configuration @@ -37,22 +37,41 @@ Example of an **incorrect** channel: ```yaml channels: - channel1: - address: /NOT_A_KEBAB/ - payload: - type: object + ticketSales: + address: transactions/ticketSales # channel address value checked by rule + messages: + ticketSaleTransaction: + $ref: '#/components/messages/ticketSaleTransaction' ``` Example of a **correct** channel: ```yaml channels: - channel1: - address: kebab-with-longer-channel-path - payload: - type: object + ticketSales: + address: transactions/ticket-sales # channel address value checked by rule + messages: + ticketSaleTransaction: + $ref: '#/components/messages/ticketSaleTransaction' ``` +### Channel rules for AsyncAPI 2.6 + +The syntax for how the channels are described changed with the AsyncAPI 3.0 release. + +If you still AsyncAPI 2.6, this rule works, and checks the channel address used as the key of the `channels` object. +For example, the rule would catch this example where `transactions/ticketSales` is used as a channel name: + +```yaml +channels: + transactions/ticketSales: # channel address value checked by rule + subscribe: + message: + $ref: '#/components/messages/ticketSaleTransaction' +``` + +Change the channel name to `transactions/ticket-sales` to comply with this rule. + ## Resources - [Rule source async3](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/async3/channels-kebab-case.ts) diff --git a/docs/rules/async/no-channel-trailing-slash.md b/docs/rules/async/no-channel-trailing-slash.md index bd29924f4..49804e5a5 100644 --- a/docs/rules/async/no-channel-trailing-slash.md +++ b/docs/rules/async/no-channel-trailing-slash.md @@ -4,12 +4,13 @@ Channel names must not have trailing slashes in their address. | AsyncAPI | Compatibility | | -------- | ------------- | -| 2.0 | ✅ | +| 2.6 | ✅ | | 3.0 | ✅ | ## API design principles -Channel names must not have trailing slashes in their address. +Depending on the protocol, the trailing slash may indicate an error or simple inconsistency between channels or documentation. +Enable this rule to make sure that no channel address includes the trailing slash. ## Configuration @@ -39,9 +40,10 @@ Example of an **incorrect** channel: ```yaml channels: channel1: - address: /trailing/ - payload: - type: object + address: events/trailing/ + messages: + event1: + $ref: '#/components/messages/event1' ``` Example of a **correct** channel: @@ -49,11 +51,29 @@ Example of a **correct** channel: ```yaml channels: channel1: - address: /expected - payload: - type: object + address: events/expected + messages: + event1: + $ref: '#/components/messages/event1' ``` +### Channel rules for AsyncAPI 2.6 + +The syntax for how the channels are described changed with the AsyncAPI 3.0 release. + +This rule also works with AsyncAPI 2.6, and checks the channel address used as the key of the `channels` object. +For example, the rule produces an error when it sees this channel with a trailing slash: + +```yaml +channels: + events/trailing/: # channel address value checked by rule + subscribe: + message: + $ref: '#/components/messages/event1' +``` + +Change the channel name to `events/expected` (or another value without a trailing slash) to comply with this rule. + ## Resources - [Rule source async3](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/async3/no-channel-trailing-slash.ts) diff --git a/docs/sidebars.yaml b/docs/sidebars.yaml index 6e12b8829..0af379e24 100644 --- a/docs/sidebars.yaml +++ b/docs/sidebars.yaml @@ -79,6 +79,8 @@ - group: Built-in rules page: rules/built-in-rules.md items: + - separator: OpenAPI + - page: rules/array-parameter-serialization.md - page: rules/boolean-parameter-prefixes.md - page: rules/component-name-unique.md - page: rules/info-contact.md @@ -131,6 +133,25 @@ - page: rules/spec-strict-refs.md - page: rules/tag-description.md - page: rules/tags-alphabetical.md + - separator: AsyncAPI + - page: rules/async/channels-kebab-case.md + - page: rules/async/no-channel-trailing-slash.md + - separator: Arazzo + - page: rules/spot/no-actions-type-end.test.md + - page: rules/spot/no-criteria-xpath.md + - page: rules/spot/parameters-not-in-body.md + - page: rules/spot/version-enum.md + - page: rules/arazzo/criteria-unique.md + - page: rules/arazzo/parameters-unique.md + - page: rules/arazzo/requestBody-replacements-unique.md + - page: rules/arazzo/sourceDescriptions-name-unique.md + - page: rules/arazzo/sourceDescriptions-type.md + - page: rules/arazzo/stepId-unique.md + - page: rules/arazzo/step-onFailure-unique.md + - page: rules/arazzo/step-onSuccess-unique.md + - page: rules/arazzo/workflow-dependsOn.md + - page: rules/arazzo/workflowId-unique.md + - page: rules/configure-rules.md label: Rule configuration - page: rules/configurable-rules.md From baaf09b08a81db46eaeeeadc53bd26f5222b7eef Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 8 Oct 2024 11:11:09 +0100 Subject: [PATCH 19/23] Apply suggestions from code review Co-authored-by: Adam Altman --- docs/rules/arazzo/parameters-unique.md | 8 ++++---- .../arazzo/requestBody-replacements-unique.md | 8 ++++---- .../arazzo/sourceDescriptions-name-unique.md | 18 +++++++++--------- docs/rules/arazzo/sourceDescriptions-type.md | 18 +++++++++--------- docs/rules/arazzo/step-onFailure-unique.md | 9 ++++----- docs/rules/arazzo/step-onSuccess-unique.md | 9 ++++----- docs/rules/arazzo/stepId-unique.md | 10 +++++----- docs/rules/arazzo/workflow-dependsOn.md | 12 ++++++------ docs/rules/arazzo/workflowId-unique.md | 12 ++++++------ 9 files changed, 51 insertions(+), 53 deletions(-) diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md index 04fbce21b..e9eaa0995 100644 --- a/docs/rules/arazzo/parameters-unique.md +++ b/docs/rules/arazzo/parameters-unique.md @@ -39,9 +39,9 @@ arazzoRules: parameters-unique: error ``` -Example of an **incorrect** parameters array: +Example of an **incorrect** `parameters` list: -```yaml Object example +```yaml Incorrect example workflows: - workflowId: get-museum-hours parameters: @@ -53,9 +53,9 @@ workflows: value: Basic Og== ``` -Example of a **correct** parameters array: +Example of a **correct** `parameters` list: -```yaml Object example +```yaml Correct example workflows: - workflowId: get-museum-hours parameters: diff --git a/docs/rules/arazzo/requestBody-replacements-unique.md b/docs/rules/arazzo/requestBody-replacements-unique.md index 306fade58..73a305d33 100644 --- a/docs/rules/arazzo/requestBody-replacements-unique.md +++ b/docs/rules/arazzo/requestBody-replacements-unique.md @@ -32,9 +32,9 @@ arazzoRules: requestBody-replacements-unique: error ``` -Example of an **incorrect** replacements array: +Example of an **incorrect** `replacements` list: -```yaml Object example +```yaml Incorrect example workflows: - workflowId: events-crud steps: @@ -51,9 +51,9 @@ workflows: value: 'another name' ``` -Example of a **correct** replacements array: +Example of a **correct** `replacements` list: -```yaml Object example +```yaml Correct example workflows: - workflowId: events-crud steps: diff --git a/docs/rules/arazzo/sourceDescriptions-name-unique.md b/docs/rules/arazzo/sourceDescriptions-name-unique.md index 465f6af1d..9fad172f6 100644 --- a/docs/rules/arazzo/sourceDescriptions-name-unique.md +++ b/docs/rules/arazzo/sourceDescriptions-name-unique.md @@ -1,6 +1,6 @@ -# sourceDescription-name-unique +# sourceDescriptions-name-unique -Requires the `name` property of the `sourceDescription` object must be unique across all source descriptions. +The `name` property of the Source Description object must be unique across all source descriptions.. | Arazzo | Compatibility | | ------ | ------------- | @@ -8,7 +8,7 @@ Requires the `name` property of the `sourceDescription` object must be unique ac ## API design principles -To avoid confusion or unexpected outputs, each `sourceDescription` object should have a unique `name` property. +To avoid confusion or unexpected outputs, each Source Description object should have a unique `name` property. ## Configuration @@ -20,7 +20,7 @@ An example configuration: ```yaml arazzoRules: - sourceDescription-name-unique: error + sourceDescriptions-name-unique: error ``` ## Examples @@ -29,12 +29,12 @@ Given the following configuration: ```yaml arazzoRules: - sourceDescription-name-unique: error + sourceDescriptions-name-unique: error ``` -Example of an **incorrect** sourceDescriptions array: +Example of an **incorrect** `sourceDescriptions` list: -```yaml Object example +```yaml Incorrect example sourceDescriptions: - name: museum-api type: openapi @@ -44,9 +44,9 @@ sourceDescriptions: url: ../petstore.yaml ``` -Example of a **correct** sourceDescriptions array: +Example of a **correct** `sourceDescriptions` list: -```yaml Object example +```yaml Correct example sourceDescriptions: - name: museum-api type: openapi diff --git a/docs/rules/arazzo/sourceDescriptions-type.md b/docs/rules/arazzo/sourceDescriptions-type.md index ca1b88723..fa52d3059 100644 --- a/docs/rules/arazzo/sourceDescriptions-type.md +++ b/docs/rules/arazzo/sourceDescriptions-type.md @@ -1,6 +1,6 @@ -# sourceDescription-type +# sourceDescriptions-type -The `type` property of the `sourceDescription` object must be either `openapi` or `arazzo`. +The `type` property of the Source Description object must be either `openapi` or `arazzo`. | Arazzo | Compatibility | | ------ | ------------- | @@ -8,7 +8,7 @@ The `type` property of the `sourceDescription` object must be either `openapi` o ## API design principles -By the Arazzo standard the possible values for `sourceDescription.type` are "openapi" or "arazzo". +According to the Arazzo spec, the possible values of the Source Description `type` are `openapi` or `arazzo`. ## Configuration @@ -20,7 +20,7 @@ An example configuration: ```yaml arazzoRules: - sourceDescription-type: error + sourceDescriptions-type: error ``` ## Examples @@ -29,12 +29,12 @@ Given the following configuration: ```yaml arazzoRules: - sourceDescription-type: error + sourceDescriptions-type: error ``` -Example of an **incorrect** sourceDescriptions array: +Example of an **incorrect** `sourceDescriptions` list: -```yaml Object example +```yaml Incorrect example sourceDescriptions: - name: museum-api type: openapi @@ -44,9 +44,9 @@ sourceDescriptions: x-serverUrl: 'http://localhost/api' ``` -Example of a **correct** sourceDescriptions array: +Example of a **correct** `sourceDescriptions` list: -```yaml Object example +```yaml Correct example sourceDescriptions: - name: museum-api type: openapi diff --git a/docs/rules/arazzo/step-onFailure-unique.md b/docs/rules/arazzo/step-onFailure-unique.md index 57cfb00dc..b7d1ea5d4 100644 --- a/docs/rules/arazzo/step-onFailure-unique.md +++ b/docs/rules/arazzo/step-onFailure-unique.md @@ -8,7 +8,6 @@ Requires all of the `onFailure` actions of the `step` object to be unique. ## API design principles -An array of failure action objects that specify what to do upon step failure. Each `onFailure` action should be unique to avoid confusion or unexpected results. ## Configuration @@ -33,9 +32,9 @@ arazzoRules: step-onFailure-unique: error ``` -Example of an **incorrect** step: +Example of an **incorrect** `onFailure` list: -```yaml Object example +```yaml Incorrect example workflows: - workflowId: get-museum-hours description: This workflow demonstrates how to get the museum opening hours and buy tickets. @@ -55,9 +54,9 @@ workflows: - reference: $components.failureActions.notify ``` -Example of a **correct** step: +Example of a **correct** `onFailure` list: -```yaml Object example +```yaml Correct example workflows: - workflowId: get-museum-hours description: This workflow demonstrates how to get the museum opening hours and buy tickets. diff --git a/docs/rules/arazzo/step-onSuccess-unique.md b/docs/rules/arazzo/step-onSuccess-unique.md index db8ed0d47..b2c24731a 100644 --- a/docs/rules/arazzo/step-onSuccess-unique.md +++ b/docs/rules/arazzo/step-onSuccess-unique.md @@ -8,7 +8,6 @@ Requires the `onSuccess` actions of the `step` object to be unique. ## API design principles -An array of success action objects that specify what to do upon step success. Each `onSuccess` action should be unique to avoid confusion or unexpected outcomes. ## Configuration @@ -33,9 +32,9 @@ arazzoRules: step-onSuccess-unique: error ``` -Example of an **incorrect** step: +Example of an **incorrect** `onSuccess` list: -```yaml Object example +```yaml Incorrect example workflows: - workflowId: get-museum-hours description: This workflow demonstrates how to get the museum opening hours and buy tickets. @@ -55,9 +54,9 @@ workflows: - reference: $components.successActions.notify ``` -Example of a **correct** step: +Example of a **correct** `onSuccess` list: -```yaml Object example +```yaml Correct example workflows: - workflowId: get-museum-hours description: This workflow demonstrates how to get the museum opening hours and buy tickets. diff --git a/docs/rules/arazzo/stepId-unique.md b/docs/rules/arazzo/stepId-unique.md index 8d88644b7..98a716b45 100644 --- a/docs/rules/arazzo/stepId-unique.md +++ b/docs/rules/arazzo/stepId-unique.md @@ -8,7 +8,7 @@ Requires the `stepId` to be unique amongst all steps described in the workflow. ## API design principles -Unique string to represent the step. +The `stepId` is a unique string that represents the step. The `stepId` must be unique amongst all steps described in the workflow. The `stepId` value is case-sensitive. @@ -34,9 +34,9 @@ arazzoRules: stepId-unique: error ``` -Example of an **incorrect** step: +Example of an **incorrect** `stepId`: -```yaml Object example +```yaml Incorrect example workflows: - workflowId: get-museum-hours-2 description: This workflow demonstrates how to get the museum opening hours and buy tickets. @@ -51,9 +51,9 @@ workflows: - condition: $statusCode == 200 ``` -Example of a **correct** step: +Example of a **correct** `stepId`: -```yaml Object example +```yaml Correct example workflows: - workflowId: get-museum-hours-2 description: This workflow demonstrates how to get the museum opening hours and buy tickets. diff --git a/docs/rules/arazzo/workflow-dependsOn.md b/docs/rules/arazzo/workflow-dependsOn.md index ae96a7ee2..eb13f8bd7 100644 --- a/docs/rules/arazzo/workflow-dependsOn.md +++ b/docs/rules/arazzo/workflow-dependsOn.md @@ -9,7 +9,7 @@ Requires the items in the `workflow` `dependsOn` property to exist and to be uni ## API design principles A list of workflows that should be completed before current workflow can be processed. -To avoid ambiguity or potential clashes, the `dependsOn` property should be unique. +To avoid ambiguity or potential clashes, the `dependsOn` list values should be unique. ## Configuration @@ -30,12 +30,12 @@ Given the following configuration: ```yaml arazzoRules: - stepId-unique: error + workflow-dependsOn: error ``` -Example of an **incorrect** `dependsOn` array: +Example of an **incorrect** `dependsOn` list: -```yaml Object example +```yaml Incorrect example workflows: - workflowId: get-museum-hours description: This workflow demonstrates how to get the museum opening hours and buy tickets. @@ -45,9 +45,9 @@ workflows: - get-museum-hours-2 ``` -Example of a **correct** `dependsOn` array: +Example of a **correct** `dependsOn` list: -```yaml Object example +```yaml Correct example workflows: - workflowId: get-museum-hours description: This workflow demonstrates how to get the museum opening hours and buy tickets. diff --git a/docs/rules/arazzo/workflowId-unique.md b/docs/rules/arazzo/workflowId-unique.md index 63a38bb88..7797363d3 100644 --- a/docs/rules/arazzo/workflowId-unique.md +++ b/docs/rules/arazzo/workflowId-unique.md @@ -8,8 +8,8 @@ Requires the `workflowId` property to be unique across all workflows. ## API design principles -Unique string to represent the workflow. -The `workflowId` must be unique across all workflows described in the API definition. +The `workflowId` is a string that represents the workflow. +According to the spec, the `workflowId` must be unique across all workflows described in the API definition. ## Configuration @@ -33,9 +33,9 @@ arazzoRules: workflowId-unique: error ``` -Example of an **incorrect** `workflows` array: +Example of an **incorrect** `workflows` list: -```yaml Object example +```yaml Incorrect example workflows: - workflowId: get-museum-hours steps: @@ -51,9 +51,9 @@ workflows: - condition: $statusCode == 200 ``` -Example of a **correct** `workflows` array: +Example of a **correct** `workflows` list: -```yaml Object example +```yaml Correct example workflows: - workflowId: get-museum-hours steps: From 00c91c067fcf2bbd4fb72c29d2c265ffc0859587 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Thu, 17 Oct 2024 11:15:09 +0100 Subject: [PATCH 20/23] docs: remove mentions of the per-format rule configuration feature until further notice --- docs/rules/arazzo/criteria-unique.md | 4 +-- docs/rules/arazzo/parameters-unique.md | 4 +-- .../arazzo/requestBody-replacements-unique.md | 4 +-- .../arazzo/sourceDescriptions-name-unique.md | 4 +-- docs/rules/arazzo/sourceDescriptions-type.md | 4 +-- docs/rules/arazzo/step-onFailure-unique.md | 4 +-- docs/rules/arazzo/step-onSuccess-unique.md | 4 +-- docs/rules/arazzo/stepId-unique.md | 4 +-- docs/rules/arazzo/workflow-dependsOn.md | 4 +-- docs/rules/arazzo/workflowId-unique.md | 4 +-- docs/rules/configure-rules.md | 35 ------------------- docs/rules/ruleset-templates.md | 26 +++++++------- 12 files changed, 33 insertions(+), 68 deletions(-) diff --git a/docs/rules/arazzo/criteria-unique.md b/docs/rules/arazzo/criteria-unique.md index d827cacaa..a1c8f5a64 100644 --- a/docs/rules/arazzo/criteria-unique.md +++ b/docs/rules/arazzo/criteria-unique.md @@ -19,7 +19,7 @@ The criteria list must not contain duplicated assertions. An example configuration: ```yaml -arazzoRules: +rules: criteria-unique: error ``` @@ -28,7 +28,7 @@ arazzoRules: Given the following configuration: ```yaml -arazzoRules: +rules: criteria-unique: error ``` diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md index e9eaa0995..3597ee2ed 100644 --- a/docs/rules/arazzo/parameters-unique.md +++ b/docs/rules/arazzo/parameters-unique.md @@ -26,7 +26,7 @@ Checks parameter lists in the following locations: An example configuration: ```yaml -arazzoRules: +rules: parameters-unique: error ``` @@ -35,7 +35,7 @@ arazzoRules: Given the following configuration: ```yaml -arazzoRules: +rules: parameters-unique: error ``` diff --git a/docs/rules/arazzo/requestBody-replacements-unique.md b/docs/rules/arazzo/requestBody-replacements-unique.md index 73a305d33..b715a68f9 100644 --- a/docs/rules/arazzo/requestBody-replacements-unique.md +++ b/docs/rules/arazzo/requestBody-replacements-unique.md @@ -19,7 +19,7 @@ The list of locations and values to set within a payload must not have duplicate An example configuration: ```yaml -arazzoRules: +rules: requestBody-replacements-unique: error ``` @@ -28,7 +28,7 @@ arazzoRules: Given the following configuration: ```yaml -arazzoRules: +rules: requestBody-replacements-unique: error ``` diff --git a/docs/rules/arazzo/sourceDescriptions-name-unique.md b/docs/rules/arazzo/sourceDescriptions-name-unique.md index 9fad172f6..cec6f48c4 100644 --- a/docs/rules/arazzo/sourceDescriptions-name-unique.md +++ b/docs/rules/arazzo/sourceDescriptions-name-unique.md @@ -19,7 +19,7 @@ To avoid confusion or unexpected outputs, each Source Description object should An example configuration: ```yaml -arazzoRules: +rules: sourceDescriptions-name-unique: error ``` @@ -28,7 +28,7 @@ arazzoRules: Given the following configuration: ```yaml -arazzoRules: +rules: sourceDescriptions-name-unique: error ``` diff --git a/docs/rules/arazzo/sourceDescriptions-type.md b/docs/rules/arazzo/sourceDescriptions-type.md index fa52d3059..2c52811ef 100644 --- a/docs/rules/arazzo/sourceDescriptions-type.md +++ b/docs/rules/arazzo/sourceDescriptions-type.md @@ -19,7 +19,7 @@ According to the Arazzo spec, the possible values of the Source Description `typ An example configuration: ```yaml -arazzoRules: +rules: sourceDescriptions-type: error ``` @@ -28,7 +28,7 @@ arazzoRules: Given the following configuration: ```yaml -arazzoRules: +rules: sourceDescriptions-type: error ``` diff --git a/docs/rules/arazzo/step-onFailure-unique.md b/docs/rules/arazzo/step-onFailure-unique.md index b7d1ea5d4..314145e62 100644 --- a/docs/rules/arazzo/step-onFailure-unique.md +++ b/docs/rules/arazzo/step-onFailure-unique.md @@ -19,7 +19,7 @@ Each `onFailure` action should be unique to avoid confusion or unexpected result An example configuration: ```yaml -arazzoRules: +rules: step-onFailure-unique: error ``` @@ -28,7 +28,7 @@ arazzoRules: Given the following configuration: ```yaml -arazzoRules: +rules: step-onFailure-unique: error ``` diff --git a/docs/rules/arazzo/step-onSuccess-unique.md b/docs/rules/arazzo/step-onSuccess-unique.md index b2c24731a..2b2bae665 100644 --- a/docs/rules/arazzo/step-onSuccess-unique.md +++ b/docs/rules/arazzo/step-onSuccess-unique.md @@ -19,7 +19,7 @@ Each `onSuccess` action should be unique to avoid confusion or unexpected outcom An example configuration: ```yaml -arazzoRules: +rules: step-onSuccess-unique: error ``` @@ -28,7 +28,7 @@ arazzoRules: Given the following configuration: ```yaml -arazzoRules: +rules: step-onSuccess-unique: error ``` diff --git a/docs/rules/arazzo/stepId-unique.md b/docs/rules/arazzo/stepId-unique.md index 98a716b45..ccd34be6b 100644 --- a/docs/rules/arazzo/stepId-unique.md +++ b/docs/rules/arazzo/stepId-unique.md @@ -21,7 +21,7 @@ The `stepId` value is case-sensitive. An example configuration: ```yaml -arazzoRules: +rules: stepId-unique: error ``` @@ -30,7 +30,7 @@ arazzoRules: Given the following configuration: ```yaml -arazzoRules: +rules: stepId-unique: error ``` diff --git a/docs/rules/arazzo/workflow-dependsOn.md b/docs/rules/arazzo/workflow-dependsOn.md index eb13f8bd7..9ee015f18 100644 --- a/docs/rules/arazzo/workflow-dependsOn.md +++ b/docs/rules/arazzo/workflow-dependsOn.md @@ -20,7 +20,7 @@ To avoid ambiguity or potential clashes, the `dependsOn` list values should be u An example configuration: ```yaml -arazzoRules: +rules: workflow-dependsOn: error ``` @@ -29,7 +29,7 @@ arazzoRules: Given the following configuration: ```yaml -arazzoRules: +rules: workflow-dependsOn: error ``` diff --git a/docs/rules/arazzo/workflowId-unique.md b/docs/rules/arazzo/workflowId-unique.md index 7797363d3..8aedd394c 100644 --- a/docs/rules/arazzo/workflowId-unique.md +++ b/docs/rules/arazzo/workflowId-unique.md @@ -20,7 +20,7 @@ According to the spec, the `workflowId` must be unique across all workflows desc An example configuration: ```yaml -arazzoRules: +rules: workflowId-unique: error ``` @@ -29,7 +29,7 @@ arazzoRules: Given the following configuration: ```yaml -arazzoRules: +rules: workflowId-unique: error ``` diff --git a/docs/rules/configure-rules.md b/docs/rules/configure-rules.md index cc731b168..c60e8466b 100644 --- a/docs/rules/configure-rules.md +++ b/docs/rules/configure-rules.md @@ -31,41 +31,6 @@ rules: Check the documentation for each rule to see if it supports additional configuration. -## Per-format configuration - -To configure rules that are different for different API formats or versions of API formats, you can use the format/version-specific configuration keys as shown in the table below: - -| Configuration | Use for | -| ------------- | ------------ | -| `oas2Rules` | OpenAPI 2.x | -| `oas3_0Rules` | OpenAPI 3.0 | -| `oas3_1Rules` | OpenAPI 3.1 | -| `async2Rules` | AsyncAPI 2.6 | -| `async3Rules` | AsyncAPI 3.0 | -| `arazzoRules` | Arazzo 1.0 | - -Using this approach is useful where you have different requirements for the different types of API description, but not necessarily every API. For example, you might choose to enable a very minimal set of rules for all formats, and add some additional restrictions for the OpenAPI 3.1 descriptions since those are expected to meet a higher standard. - -The following configuration file shows an example of a minimal ruleset configuration, with some rules adjusted (both increased in severity and disabled) for different OpenAPI description formats: - -```yaml -extends: - - minimal - -rules: - info-description: warn - -oas2Rules: - no-unresolved-refs: off - -oas3_1Rules: - info-license: error - no-ambiguous-paths: error - operation-operationId-unique: error -``` - -Use these settings alongside `rules` configuration to tune the linting for each API description format. - ## Per-API configuration You can set different rules for different APIs by adding a `rules` object under each API in `apis`. diff --git a/docs/rules/ruleset-templates.md b/docs/rules/ruleset-templates.md index 32acf5e15..ab274b9f8 100644 --- a/docs/rules/ruleset-templates.md +++ b/docs/rules/ruleset-templates.md @@ -5,8 +5,8 @@ Redocly CLI includes some default rulesets to get you started quickly. To edit/adjust the rules you use in your own projects, [configure your rules](./configure-rules.md) accordingly to override any settings from the original ruleset. On this page, each ruleset is included for each of the supported API description formats. -You can use this information for your own reference, or copy/paste them in order to use separate configuration for each API format. -Consult the relevant section below, each code sample is formatted to be included in `redocly.yaml` directly. +You can use this information for your own reference, or copy/paste them in order to use [separate configuration for each API](../configuration/apis.md). +Consult the format-specific sections below, each code sample is formatted to be included in `redocly.yaml` directly. More information and examples for individual rules can be found in the [built-in rules documentation](./built-in-rules.md). @@ -17,7 +17,7 @@ The minimal rulesets are a decent baseline that you can use to selective enable ### Minimal ruleset: OpenAPI 3.1 ```yaml -oas3_1Rules: +rules: info-contact: off info-license: off info-license-url: off @@ -79,7 +79,7 @@ oas3_1Rules: ### Minimal ruleset: OpenAPI 3.0 ```yaml -oas3_0Rules: +rules: info-contact: off info-license: off info-license-url: off @@ -141,7 +141,7 @@ oas3_0Rules: ### Minimal ruleset: OpenAPI 2.0 ```yaml -oas2Rules: +rules: info-contact: off info-license: off info-license-url: off @@ -191,7 +191,7 @@ oas2Rules: ### Minimal ruleset: AsyncAPI 3.0 ```yaml -async3Rules: +rules: spec: error info-contact: off info-license-strict: off @@ -205,7 +205,7 @@ async3Rules: ### Minimal ruleset: AsyncAPI 2.6 ```yaml -async2Rules: +rules: spec: error info-contact: off info-license-strict: off @@ -219,7 +219,7 @@ async2Rules: ### Minimal ruleset: Arazzo 1.0 ```yaml -arazzoRules: +rules: spec: error parameters-not-in-body: off sourceDescription-type: off @@ -350,7 +350,7 @@ oas3_1Rules: ### Recommended ruleset: OpenAPI 3.0 ```yaml -oas3_0Rules: +rules: info-contact: off info-license: warn info-license-url: off @@ -412,7 +412,7 @@ oas3_0Rules: ### Recommended ruleset: OpenAPI 2.0 ```yaml -oas2Rules: +rules: info-contact: off info-license: warn info-license-url: off @@ -462,7 +462,7 @@ oas2Rules: ### Recommended ruleset: AsyncAPI 3.0 ```yaml -async3Rules: +rules: spec: error info-contact: off info-license-strict: warn @@ -476,7 +476,7 @@ async3Rules: ### Recommended ruleset: AsyncAPI 2.6 ```yaml -async2Rules: +rules: spec: error info-contact: off info-license-strict: warn @@ -490,7 +490,7 @@ async2Rules: ### Recommended ruleset: Arazzo 1.0 ```yaml -arazzoRules: +rules: spec: error parameters-not-in-body: warn sourceDescription-type: error From b3f89f38546d19cde8283d7eeaf55b47f7209b14 Mon Sep 17 00:00:00 2001 From: DmitryAnansky Date: Fri, 18 Oct 2024 17:20:12 +0300 Subject: [PATCH 21/23] chore: add sourceDescriptions-not-empty rule docs --- .../arazzo/sourceDescriptions-not-empty.md | 93 +++++++++++++++++++ docs/rules/built-in-rules.md | 1 + 2 files changed, 94 insertions(+) create mode 100644 docs/rules/arazzo/sourceDescriptions-not-empty.md diff --git a/docs/rules/arazzo/sourceDescriptions-not-empty.md b/docs/rules/arazzo/sourceDescriptions-not-empty.md new file mode 100644 index 000000000..cfa14beaf --- /dev/null +++ b/docs/rules/arazzo/sourceDescriptions-not-empty.md @@ -0,0 +1,93 @@ +# sourceDescriptions-not-empty + +The Source Description must have at least one entry. + +| Arazzo | Compatibility | +| ------ | ------------- | +| 1.0.0 | ✅ | + +## API design principles + +According to the Arazzo spec `sourceDescriptions` is required and the list must have at least one entry. + +## Configuration + +| Option | Type | Description | +| -------- | ------ | ------------------------------------------------------- | +| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. | + +An example configuration: + +```yaml +rules: + sourceDescriptions-not-empty: error +``` + +## Examples + +Given the following configuration: + +```yaml +rules: + sourceDescriptions-not-empty: error +``` + +Example of an **incorrect** usage: + +```yaml Incorrect example +arazzo: '1.0.0' +info: + title: Cool API + version: 1.0.0 + description: A cool API +sourceDescriptions: [] +workflows: + - workflowId: get-museum-hours + description: This workflow demonstrates how to get the museum opening hours and buy tickets. + parameters: + - in: header + name: Authorization + value: Basic Og== + steps: + - stepId: get-museum-hours + description: >- + Get museum hours by resolving request details with getMuseumHours operationId from openapi.yaml description. + operationId: $sourceDescriptions.museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 +``` + +Example of a **correct** usage: + +```yaml Correct example +arazzo: '1.0.0' +info: + title: Cool API + version: 1.0.0 + description: A cool API +sourceDescriptions: + - name: museum-api + type: openapi + url: openapi.yaml + - name: another-api + type: openapi + url: openapi.yaml +workflows: + - workflowId: get-museum-hours + description: This workflow demonstrates how to get the museum opening hours and buy tickets. + parameters: + - in: header + name: Authorization + value: Basic Og== + steps: + - stepId: get-museum-hours + description: >- + Get museum hours by resolving request details with getMuseumHours operationId from openapi.yaml description. + operationId: $sourceDescriptions.museum-api.getMuseumHours + successCriteria: + - condition: $statusCode == 200 +``` + +## Resources + +- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/sourceDescriptions-not-empty.ts) diff --git a/docs/rules/built-in-rules.md b/docs/rules/built-in-rules.md index a177b0b94..5da31a89b 100644 --- a/docs/rules/built-in-rules.md +++ b/docs/rules/built-in-rules.md @@ -128,6 +128,7 @@ Within the Arazzo family of rules, there are rules for the main Arazzo specifica - [step-onSuccess-unique](./arazzo/step-onSuccess-unique.md): the `onSuccess` actions of the `step` object must be unique - [workflow-dependsOn](./arazzo/workflow-dependsOn.md): the items in the `workflow` `dependsOn` property must exist and be unique - [workflowId-unique](./arazzo/workflowId-unique.md): the `workflowId` property must be unique across all workflows +- [sourceDescriptions-not-empty](./arazzo/sourceDescriptions-not-empty.md): the `sourceDescriptions` must be defined and the list must have at least one entry. ### Spot From 47a77015f783e5687004fc79365324d94056f3a4 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 25 Oct 2024 14:30:40 +0100 Subject: [PATCH 22/23] docs: Adjust design principles sections of Arazzo rules --- docs/rules/arazzo/criteria-unique.md | 4 ++-- docs/rules/arazzo/parameters-unique.md | 4 ++-- docs/rules/arazzo/requestBody-replacements-unique.md | 2 +- docs/rules/arazzo/sourceDescriptions-name-unique.md | 5 +++-- docs/rules/arazzo/sourceDescriptions-not-empty.md | 5 +++-- docs/rules/arazzo/sourceDescriptions-type.md | 5 +++-- docs/rules/arazzo/step-onFailure-unique.md | 3 ++- docs/rules/arazzo/step-onSuccess-unique.md | 3 ++- docs/rules/arazzo/stepId-unique.md | 9 +++++---- docs/rules/arazzo/workflow-dependsOn.md | 3 +-- docs/rules/arazzo/workflowId-unique.md | 6 +++--- 11 files changed, 27 insertions(+), 22 deletions(-) diff --git a/docs/rules/arazzo/criteria-unique.md b/docs/rules/arazzo/criteria-unique.md index a1c8f5a64..08ef66e8e 100644 --- a/docs/rules/arazzo/criteria-unique.md +++ b/docs/rules/arazzo/criteria-unique.md @@ -6,9 +6,9 @@ The criteria list must not contain duplicated assertions. | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles -The criteria list must not contain duplicated assertions. +To avoid redundancy and confusion, the assertions in the criteria list must not be duplicated. ## Configuration diff --git a/docs/rules/arazzo/parameters-unique.md b/docs/rules/arazzo/parameters-unique.md index 3597ee2ed..5748de4a3 100644 --- a/docs/rules/arazzo/parameters-unique.md +++ b/docs/rules/arazzo/parameters-unique.md @@ -6,12 +6,12 @@ Requires unique values in the `parameters` lists. | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles A list of `parameters` that are applicable to a step or all the steps described in a workflow should not contain duplicates. If duplicates are present, unexpected parameter overrides could cause problems. -Checks parameter lists in the following locations: +This ruled checks parameter lists in the following locations: - `workflows.[workflow].parameters` - `workflows.[workflow[.steps.[step].parameters` diff --git a/docs/rules/arazzo/requestBody-replacements-unique.md b/docs/rules/arazzo/requestBody-replacements-unique.md index b715a68f9..b1093d22a 100644 --- a/docs/rules/arazzo/requestBody-replacements-unique.md +++ b/docs/rules/arazzo/requestBody-replacements-unique.md @@ -6,7 +6,7 @@ Requires the `replacements` in the `step.requestBody` object to be unique. | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles The list of locations and values to set within a payload must not have duplicates that might result in content override. diff --git a/docs/rules/arazzo/sourceDescriptions-name-unique.md b/docs/rules/arazzo/sourceDescriptions-name-unique.md index cec6f48c4..892bb0241 100644 --- a/docs/rules/arazzo/sourceDescriptions-name-unique.md +++ b/docs/rules/arazzo/sourceDescriptions-name-unique.md @@ -1,14 +1,15 @@ # sourceDescriptions-name-unique -The `name` property of the Source Description object must be unique across all source descriptions.. +The `name` property of the Source Description object must be unique across all source descriptions. | Arazzo | Compatibility | | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles To avoid confusion or unexpected outputs, each Source Description object should have a unique `name` property. +Especially in a longer list of sources, this could be difficult to identify and could have unwanted side effects. ## Configuration diff --git a/docs/rules/arazzo/sourceDescriptions-not-empty.md b/docs/rules/arazzo/sourceDescriptions-not-empty.md index cfa14beaf..0426fcdd1 100644 --- a/docs/rules/arazzo/sourceDescriptions-not-empty.md +++ b/docs/rules/arazzo/sourceDescriptions-not-empty.md @@ -6,9 +6,10 @@ The Source Description must have at least one entry. | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles -According to the Arazzo spec `sourceDescriptions` is required and the list must have at least one entry. +Source descriptions are an important part of an Arazzo description, and at least one entry must exist. +If the list is empty, this could indicate an omission or another problem; this rule will alert you if that happens. ## Configuration diff --git a/docs/rules/arazzo/sourceDescriptions-type.md b/docs/rules/arazzo/sourceDescriptions-type.md index 2c52811ef..0b0641e14 100644 --- a/docs/rules/arazzo/sourceDescriptions-type.md +++ b/docs/rules/arazzo/sourceDescriptions-type.md @@ -6,9 +6,10 @@ The `type` property of the Source Description object must be either `openapi` or | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles -According to the Arazzo spec, the possible values of the Source Description `type` are `openapi` or `arazzo`. +Arazzo currently supports either an OpenAPI file or another Arazzo file as the source description. +This rule makes sure that the type is clearly identified and is one of the supported types. ## Configuration diff --git a/docs/rules/arazzo/step-onFailure-unique.md b/docs/rules/arazzo/step-onFailure-unique.md index 314145e62..2911951e7 100644 --- a/docs/rules/arazzo/step-onFailure-unique.md +++ b/docs/rules/arazzo/step-onFailure-unique.md @@ -6,9 +6,10 @@ Requires all of the `onFailure` actions of the `step` object to be unique. | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles Each `onFailure` action should be unique to avoid confusion or unexpected results. +A duplicate could indicate a mistake, or cause unwanted side effects if not detected by this rule. ## Configuration diff --git a/docs/rules/arazzo/step-onSuccess-unique.md b/docs/rules/arazzo/step-onSuccess-unique.md index 2b2bae665..08eb5942c 100644 --- a/docs/rules/arazzo/step-onSuccess-unique.md +++ b/docs/rules/arazzo/step-onSuccess-unique.md @@ -6,9 +6,10 @@ Requires the `onSuccess` actions of the `step` object to be unique. | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles Each `onSuccess` action should be unique to avoid confusion or unexpected outcomes. +A duplicate could indicate a mistake, or cause unwanted side effects if not detected by this rule. ## Configuration diff --git a/docs/rules/arazzo/stepId-unique.md b/docs/rules/arazzo/stepId-unique.md index ccd34be6b..90949aa71 100644 --- a/docs/rules/arazzo/stepId-unique.md +++ b/docs/rules/arazzo/stepId-unique.md @@ -6,11 +6,12 @@ Requires the `stepId` to be unique amongst all steps described in the workflow. | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles -The `stepId` is a unique string that represents the step. -The `stepId` must be unique amongst all steps described in the workflow. -The `stepId` value is case-sensitive. +The steps in a workflow each have a required `stepId` field and this must be unique in order to conform with the specification. +This rule catches any accidental duplication of `stepId` values so that the workflow is valid. + +Note: `stepId` values are considered to be case-sensitive. ## Configuration diff --git a/docs/rules/arazzo/workflow-dependsOn.md b/docs/rules/arazzo/workflow-dependsOn.md index 9ee015f18..666ff4f95 100644 --- a/docs/rules/arazzo/workflow-dependsOn.md +++ b/docs/rules/arazzo/workflow-dependsOn.md @@ -6,9 +6,8 @@ Requires the items in the `workflow` `dependsOn` property to exist and to be uni | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles -A list of workflows that should be completed before current workflow can be processed. To avoid ambiguity or potential clashes, the `dependsOn` list values should be unique. ## Configuration diff --git a/docs/rules/arazzo/workflowId-unique.md b/docs/rules/arazzo/workflowId-unique.md index 8aedd394c..208248e97 100644 --- a/docs/rules/arazzo/workflowId-unique.md +++ b/docs/rules/arazzo/workflowId-unique.md @@ -6,10 +6,10 @@ Requires the `workflowId` property to be unique across all workflows. | ------ | ------------- | | 1.0.0 | ✅ | -## API design principles +## Design principles -The `workflowId` is a string that represents the workflow. -According to the spec, the `workflowId` must be unique across all workflows described in the API definition. +According to the spec, the `workflowId` must be unique across all workflows described in the API description. +Duplication could also indicate a typo or other mistake; this rule alerts you if such a situation arises. ## Configuration From 91b04e4529dff922b8f268c9216d147133a12ce8 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 25 Oct 2024 14:42:26 +0100 Subject: [PATCH 23/23] docs: Make vale happy --- docs/rules/arazzo/sourceDescriptions-not-empty.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rules/arazzo/sourceDescriptions-not-empty.md b/docs/rules/arazzo/sourceDescriptions-not-empty.md index 0426fcdd1..16ce2c55c 100644 --- a/docs/rules/arazzo/sourceDescriptions-not-empty.md +++ b/docs/rules/arazzo/sourceDescriptions-not-empty.md @@ -9,7 +9,7 @@ The Source Description must have at least one entry. ## Design principles Source descriptions are an important part of an Arazzo description, and at least one entry must exist. -If the list is empty, this could indicate an omission or another problem; this rule will alert you if that happens. +If the list is empty, this could indicate an omission or another problem; this rule alerts you if that happens. ## Configuration