docs: copyedit, remove diagrams and page slugs, update for accuracy

Redocly · Sep 10, 2024 · 7124c2a · 7124c2a
1 parent 5517730
commit 7124c2a
Show file tree

Hide file tree

Showing 16 changed files with 59 additions and 245 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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: