diff --git a/docs/rules/arazzo/sourceDescriptions-name-unique.md b/docs/rules/arazzo/sourceDescriptions-name-unique.md new file mode 100644 index 0000000000..2a23f9d1c4 --- /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 0000000000..52c18ea255 --- /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 0000000000..5a97b8c272 --- /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 0000000000..d57e53e457 --- /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 0000000000..c002ab034e --- /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 0000000000..338cd99d50 --- /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 0000000000..a987453330 --- /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 b3388733da..ab0dadcb2c 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 f6038adb1e..9dc634c959 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 ffdaadfe4f..b9e53e3e61 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'; @@ -19,7 +19,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 efc4331394..e5cd61916b 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) {