docs: add a guide for linting Arazzo files (#1642)

* docs: add a guide for linting Arazzo files

* chore: fix formatting

* Update docs/guides/lint-arazzo.md

* Apply suggestions from code review

Co-authored-by: JLekawa <164185257+JLekawa@users.noreply.github.com>

* docs: More PR feedback and add the output sample

* docs: fix a link

---------

Co-authored-by: JLekawa <164185257+JLekawa@users.noreply.github.com>

docs/guides/index.md

@@ -22,6 +22,12 @@ content:
     - header: Replace the server URL
       link: docs/cli/guides/replace-servers-url
       text: How to replace the server URL in different environments.
+    - header: Lint AsyncAPI descriptions
+      link: docs/cli/guides/lint-asyncapi
+      text: API governance for async and streaming API applications.
+    - header: Lint Arazzo descriptions
+      link: docs/cli/guides/lint-arazzo
+      text: Check the validity of Arazzo descriptions for workflows.
     - header: Change the OAuth2 token URL
       link: docs/cli/guides/change-token-url
       text: How to change the OAuth2 token URL.

docs/guides/lint-arazzo.md

@@ -0,0 +1,113 @@
+# Lint Arazzo with Redocly CLI
+
+[Arazzo](https://spec.openapis.org/arazzo/latest.html#arazzo-specification) is an open standard from the OpenAPI Initiative for describing a sequence API calls, defining success criteria, and adding response content to subsequent API calls.
+While under development, this standard was also known as "OpenAPI Workflows".
+Redocly CLI offers support for checking that your Arazzo files are valid.
+
+{% admonition type="info" name="Experimental Arazzo support" %}
+This feature is at an early stage, please send us lots of [feedback](https://github.com/redocly/redocly-cli/issues/new)!
+{% /admonition %}
+
+## Lint an Arazzo file
+
+Use your existing Arazzo files, or use the Arazzo examples in the [Museum API project](https://github.com/Redocly/museum-openapi-example) if you'd prefer to use sample data to try things out.
+
+**Pro-tip:** linting is much more interesting if the file actually does contain problems.
+Be your own chaos monkey and introduce some errors before you proceed!
+
+Lint using a command like the following:
+
+```bash
+redocly lint arazzo/museum-api.arazzo.yaml
+```
+
+If the file does not match the specification, the tool shows the details of each error that it finds, like in the following example:
+
+```text
+validating arazzo/museum-api.arazzo.yaml...
+[1] arazzo/museum-api.arazzo.yaml:18:5 at #/workflows/0
+
+The field `workflowId` must be present on this level.
+
+16 |
+17 | workflows:
+18 |   - workflooId: get-museum-hours
+19 |     description: >-
+ … |     < 20 more lines >
+40 |   - workflowId: events-crud
+41 |     description: >-
+42 |       This workflow demonstrates how to list, create, update, and delete special events at the museum.
+
+Error was generated by the spec rule.
+
+
+[2] arazzo/museum-api.arazzo.yaml:18:5 at #/workflows/0/workflooId
+
+Property `workflooId` is not expected here.
+
+Did you mean: workflowId ?
+
+16 |
+17 | workflows:
+18 |   - workflooId: get-museum-hours
+19 |     description: >-
+20 |       This workflow demonstrates how to get the museum opening hours and buy tickets.
+
+Error was generated by the spec rule.
+
+
+arazzo/museum-api.arazzo.yaml: validated in 14ms
+
+❌ Validation failed with 2 errors.
+run `redocly lint --generate-ignore-file` to add all problems to the ignore file.
+```
+
+{% admonition type="info" name="Validation only" %}
+No additional rules or configuration are available for Arazzo in the current version of Redocly CLI; the tool merely checks that the file meets the specification.
+{% /admonition %}
+
+## Choose output format
+
+Since Redocly CLI is already a fully-featured lint tool, additional features such as a choice of formats are already included.
+
+Get a report in **Markdown format** with the following command:
+
+```bash
+redocly lint --format=markdown arazzo/museum-api.arazzo.yaml
+```
+
+Choose your preferred output format from `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `github-actions`, `markdown`, or `summary`.
+The [lint command page](../commands/lint.md) has full details of the command's options.
+
+## Add Arazzo linting to GitHub Actions
+
+To make sure that your Arazzo description remains valid, add linting to your CI (Continuous Integration) setup.
+You can use Redocly CLI with the `github-actions` output format to get annotations directly in your pull request if any validation problems are found.
+The following snippet shows an example of configuring a GitHub action for linting:
+
+```yaml
+name: Validate museum Arazzo descriptions
+
+on: [pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up node
+        uses: actions/setup-node@v4
+      - name: Install Redocly CLI
+        run: npm install -g @redocly/cli@latest
+      - name: Run linting
+        run: redocly lint arazzo/*yaml --format=github-actions
+```
+
+With this action in place, the intentional errors I added to the Arazzo description are shown as annotations on the pull request:
+
+![Screenshot of annotation flagging "workfloo" as an unexpected value and suggesting "workflow"](images/museum-arazzo-lint.png)
+
+## Participate in Redocly CLI
+
+Redocly CLI is an open source project, so we invite you to check out the [code on GitHub](https://github.com/Redocly/redocly-cli/), and open issues to report problems or request features.

docs/sidebars.yaml

@@ -49,6 +49,7 @@
         - label: Enforce response contents
           page: guides/response-contains-property.md
         - page: guides/lint-asyncapi.md
+        - page: guides/lint-arazzo.md
         - label: Change the OAuth2 token URL
           page: guides/change-token-url.md
         - label: Hide OpenAPI specification extensions