docs: respect and generate-arazzo commands (#1931)

adamaltman · web-flow · commit 8f4a1d6da1a5 · 2025-02-25T09:14:42.000-06:00
diff --git a/.mlc.toml b/.mlc.toml
@@ -1,5 +1,5 @@
 # Ignore these links, we can't check them from this subproject
-ignore-links=["../../*", "/docs/*",
+ignore-links=["../../*", "/docs/*", "/learn/*",
 	# skip this, it redirects to user login
 	"https://github.com/Redocly/redocly-cli/issues/*"
 ]
diff --git a/docs/commands/generate-arazzo.md b/docs/commands/generate-arazzo.md
@@ -2,32 +2,25 @@
 slug:
   - /docs/cli/commands/generate-arazzo
   - /docs/respect/commands/generate-arazzo
-rbac:
-  authenticated: read
 ---
 
 # `generate-arazzo`
 
 Auto-generate an Arazzo description based on an OpenAPI description file.
 
-If `examples` are provided in the OpenAPI description, they are used as input data for test requests.
-If `schema` is provided, the config generates fake data based on the description schema.
-By default, data for requests comes from the description at runtime.
-To materialize tests with the data, use the `--extended` option.
-
-The `--extended` option also demonstrates how Respect gets data from an OpenAPI description.
-
 {% admonition type="warning" %}
 
 Given the nature of OpenAPI, the generated Arazzo description is not a complete test file and may not function. Dependencies between endpoints are not resolved.
 
 It acts as a starting point for a test file and needs to be extended to be functional.
 {% /admonition %}
 
+The first HTTP response is used as the success criteria for each step.
+
 ## Usage
 
 ```sh
-npx @redocly/cli generate-arazzo <your-OAS-description-file> [-o | --output-file] [--extended]
+npx @redocly/cli generate-arazzo <your-OAS-description-file> [-o | --output-file]
 ```
 
 ## Options
@@ -42,23 +35,88 @@ npx @redocly/cli generate-arazzo <your-OAS-description-file> [-o | --output-file
 
 - -o, --output-file
 - string
-- Path to the OAS description file. If the file name is not provided, the default name is used - `auto-generate.yaml`. Example: `npx @redocly/cli generate-arazzo OAS-file.yaml -o=example.yaml`
+- Path to the OAS description file. If the file name is not provided, the default name is used - `auto-generate.arazzo.yaml`. Example: `npx @redocly/cli generate-arazzo OAS-file.yaml -o=example.arazzo.yaml`
 
----
-
-- --extended
-- boolean
-- By default, data for requests comes from the description at runtime. This option generates a test config file with data populated from the description. Example: `npx @redocly/cli generate-arazzo OAS-file.yaml -o=example.yaml --extended`.
+{% /table %}
 
----
+## Examples
 
-- --with-expectations
-- boolean
-- By default, data for requests comes from the description at runtime. This option generates a test config file with data populated from the description with additional expectations. Example: `npx @redocly/cli generate-arazzo OAS-file.yaml -o=example.yaml --with-expectations`.
+Run the command: `npx @redocly/cli generate-arazzo 'https://warp-single-sidebar.redocly.app/_spec/apis/index.yaml'`
+
+The command generates a `auto-generate.arazzo.yaml` file in the current directory.
+
+The contents of the generated file are:
+
+```yaml {% title="auto-generate.arazzo.yaml" %}
+arazzo: 1.0.1
+info:
+  title: Warp API
+  version: 1.0.0
+sourceDescriptions:
+  - name: index
+    type: openapi
+    url: https://warp-single-sidebar.redocly.app/_spec/apis/index.yaml
+workflows:
+  - workflowId: post-timelines-workflow
+    steps:
+      - stepId: post-timelines-step
+        operationId: $sourceDescriptions.warp.createTimeline
+        successCriteria:
+          - condition: $statusCode == 201
+  - workflowId: get-timelines-workflow
+    steps:
+      - stepId: get-timelines-step
+        operationId: $sourceDescriptions.warp.listTimelines
+        successCriteria:
+          - condition: $statusCode == 200
+  - workflowId: delete-timeline-{timeline_id}-workflow
+    steps:
+      - stepId: delete-timeline-{timeline_id}-step
+        operationId: $sourceDescriptions.warp.deleteTimeline
+        successCriteria:
+          - condition: $statusCode == 204
+  - workflowId: post-travels-workflow
+    steps:
+      - stepId: post-travels-step
+        operationId: $sourceDescriptions.warp.timeTravel
+        successCriteria:
+          - condition: $statusCode == 200
+  - workflowId: post-items-workflow
+    steps:
+      - stepId: post-items-step
+        operationId: $sourceDescriptions.warp.registerItem
+        successCriteria:
+          - condition: $statusCode == 200
+  - workflowId: post-events-workflow
+    steps:
+      - stepId: post-events-step
+        operationId: $sourceDescriptions.warp.manipulateEvent
+        successCriteria:
+          - condition: $statusCode == 200
+  - workflowId: post-anchors-workflow
+    steps:
+      - stepId: post-anchors-step
+        operationId: $sourceDescriptions.warp.setAnchor
+        successCriteria:
+          - condition: $statusCode == 201
+  - workflowId: post-paradox-checks-workflow
+    steps:
+      - stepId: post-paradox-checks-step
+        operationId: $sourceDescriptions.warp.checkParadox
+        successCriteria:
+          - condition: $statusCode == 200
+  - workflowId: get-monitor-timeline-workflow
+    steps:
+      - stepId: get-monitor-timeline-step
+        operationId: $sourceDescriptions.warp.monitorTimeline
+        successCriteria:
+          - condition: $statusCode == 200
+```
 
-{% /table %}
+The generated file is not a complete test file and needs to be extended to be functional.
 
-<!-- TODO
-## Examples
+## Resources
 
-## Resources -->
+- [Learn more about Arazzo](/learn/arazzo/what-is-arazzo).
+- [Lint command](./lint.md) to lint your Arazzo description.
+- [Respect command](./respect.md) to execute your Arazzo description.
diff --git a/docs/commands/respect.md b/docs/commands/respect.md
@@ -2,19 +2,16 @@
 slug:
   - /docs/cli/commands/respect
   - /docs/respect/commands/respect
-rbac:
-  authenticated: read
 ---
 
 # `respect`
 
 Use this command to execute API tests described in an Arazzo description.
-In addition to the Arazzo specification, Respect supports specification extensions for API testing: `x-operation` and `x-serverUrl`.
 
 ## Usage
 
 ```sh
-npx @redocly/cli respect <your-test-file | multiple files | files bash query> [-w | --workflow] [-s | --skip] [-v | --verbose] [-i | --input]
+npx @redocly/cli respect <your-test-file | multiple files | files bash query> [-w | --workflow] [-s | --skip] [-v | --verbose] [-i | --input] [-S | --server] [-H | --har-output] [-J | --json-output]
 ```
 
 ## Options
@@ -30,7 +27,7 @@ npx @redocly/cli respect <your-test-file | multiple files | files bash query> [-
 - -w, --workflow
 - [string]
 - Workflow names from the test file to run.
-  For example, the following command runs "first-flow" and "second-flow" workflows from the `test-file.yaml` Arazzo description: `npx @redocly/cli respect test-file.yaml --workflow first-flow second-flow`
+  For example, the following command runs "first-flow" and "second-flow" workflows from the `test-file.yaml` Arazzo description: `npx @redocly/cli respect test-file.yaml --workflow first-flow second-flow`.
   {% admonition type="warning" %}
   The `--workflow` option can't be used with `--skip`.
   {% /admonition %}
@@ -40,7 +37,7 @@ npx @redocly/cli respect <your-test-file | multiple files | files bash query> [-
 - -s, --skip
 - [string]
 - Workflow names from the test file to skip.
-  For example, the following command skips the "first-flow" workflow from the `test-file.yaml` Arazzo description: `npx @redocly/cli respect test-file.yaml --skip first-flow`
+  For example, the following command skips the "first-flow" workflow from the `test-file.yaml` Arazzo description: `npx @redocly/cli respect test-file.yaml --skip first-flow`.
   {% admonition type="warning" name="Warning" %}
   The `--skip` option can't be used with `--workflow`.
   {% /admonition %}
@@ -50,20 +47,20 @@ npx @redocly/cli respect <your-test-file | multiple files | files bash query> [-
 - -v, --verbose
 - boolean
 - Runs the command in verbose mode to help with troubleshooting issues.
-  For example, the following command runs all workflows from the `test-file.yaml` Arazzo description in verbose mode: `npx @redocly/cli respect test-file.yaml --verbose`
+  For example, the following command runs all workflows from the `test-file.yaml` Arazzo description in verbose mode: `npx @redocly/cli respect test-file.yaml --verbose`.
 
 ---
 
 - --har-output
 - string
 - Path for the `har` file for saving logs.
-  For example, the following command runs all workflows from the `test-file.yaml` Arazzo description and saves the logs to the `logs.har` file: `npx @redocly/cli respect test-file.yaml --har-output='logs.har'`
+  For example, the following command runs all workflows from the `test-file.yaml` Arazzo description and saves the logs to the `logs.har` file: `npx @redocly/cli respect test-file.yaml --har-output='logs.har'`.
 
 ---
 
 - --json-output
 - string
-- Path for the JSON file for saving logs. For example, the following command runs all workflows from the `test-file.yaml` Arazzo description and saves the logs to the `logs.json` file:`npx @redocly/cli respect test-file.yaml --json-output='logs.json'`
+- Path for the JSON file for saving logs. For example, the following command runs all workflows from the `test-file.yaml` Arazzo description and saves the logs to the `logs.json` file:`npx @redocly/cli respect test-file.yaml --json-output='logs.json'`.
 
 ---
 
@@ -81,19 +78,10 @@ npx @redocly/cli respect <your-test-file | multiple files | files bash query> [-
 - --server
 - string
 - Server overrides for the `sourceDescriptions` object.
-  For example, the following command runs all workflows from the `test-file.yaml` Arazzo description and instead of using the server listed in the API description, uses the server at `https://test.com`: `npx @redocly/cli respect test-file.yaml --server test=https://test.com`
+  For example, the following command runs all workflows from the `test-file.yaml` Arazzo description and instead of using the server listed in the API description, uses the server at `https://test.com`: `npx @redocly/cli respect test-file.yaml --server test=https://test.com`.
 
   You can also pass the server overrides as an environment variable, as in the following example:
-  `REDOCLY_CLI_RESPECT_SERVER="test=https://test.com"`
-
----
-
-- --residency
-- string
-- If not logged in already, use the residency location of the Reunite application.
-  Default: `us`.
-  You can also pass the residency as an environment variable, as in the following example:
-  `REDOCLY_CLI_RESPECT_RESIDENCY='eu'`
+  `REDOCLY_CLI_RESPECT_SERVER="test=https://test.com"`.
 
 {% /table %}
 
@@ -158,7 +146,7 @@ Running workflow warp.arazzo.yaml / missionLostInvention
 
 ## Resources
 
-<!-- - Learn more about using mTLS with Respect in [Use mTLS](/docs/respect/guides/mtls-cli).
+- Learn more about using mTLS with Respect in [Use mTLS](/docs/respect/guides/mtls-cli).
 - Follow steps to test API sequences in [Test a sequence of API calls](/docs/respect/guides/test-api-sequences).
 - Learn what Respect is and how you can use it to test API in the [Respect](/docs/respect) concept document.
-- [Learn Arazzo](/learn/arazzo/what-is-arazzo). -->
+- [Learn Arazzo](/learn/arazzo/what-is-arazzo).

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`# Ignore these links, we can't check them from this subproject`
`2`		`-ignore-links=["../../", "/docs/",`
	`2`	`+ignore-links=["../../", "/docs/", "/learn/*",`
`3`	`3`	`# skip this, it redirects to user login`
`4`	`4`	`"https://github.com/Redocly/redocly-cli/issues/*"`
`5`	`5`	`]`