docs(other): respect usage article by DmitryAnansky · Pull Request #149 · Redocly/website

DmitryAnansky · 2025-10-27T17:51:32Z

What/Why/How?

Added two first articles related to practical usage of the Respect command, using Code Walkthrough.
The idea is to provide a set of ready-to-use articles/templates connected to the Redocly Cafe API, allowing users to easily explore how it works and adopt them for similar use cases.

Reference

Testing

Screenshots (optional)

Check yourself

Code is linted
Tested
All new/updated code is covered with tests

Security

Security impact of change has been considered
Code follows company security practices and guidelines

DmitryAnansky · 2026-04-30T15:09:39Z

+  <b>IMPORTANT: the API description intentionally contains discrepancies for demonstration purposes.</b>
+
+```yaml
+openapi: 3.1.0


Using the 3.1.0 example, as VSCE currently doesn’t support rendering 3.2.0 and we would like to allow users to have valid preview.

DmitryAnansky · 2026-04-30T15:18:39Z

 - page: ./linting-arazzo-workflows.md
 - page: ./testing-arazzo-workflows.md
 - page: ./documenting-multiple-apis-using-arazzo.md
+- group: Respect practical example series


Is it ok to keep it as learn/arazzo articles or should we transform them into blog posts?

tatomyr · 2026-05-12T09:47:44Z

+
+Arazzo provides a standard way to describe API workflows declaratively. Respect uses those workflows to run API contract tests against real API behavior.
+
+With this approach, teams can maintain API test coverage, detect documentation drift earlier, and share executable API workflows across engineering, QA, and documentation teams.


Do we want to put a link to the next part of this tutorial somewhere here?

cc: @Redocly/technical-writers

DmitryAnansky · 2026-05-12T09:58:48Z

+- The status code and content type checks pass because the response matches the documented response metadata.
+- The schema check fails because the response body shape does not match the documented schema.
+
+<details>


@Redocly/technical-writers is it better to use terminal output screenshot here?

tatomyr · 2026-05-14T13:59:26Z

+This article shows how to use Respect, powered by Arazzo workflows, for API contract testing.
+You will learn how to describe an API workflow, execute it with Redocly CLI, and use the results to find mismatches between an OpenAPI description and the real API behavior.
+
+You will cover the following topics:
+
+Practical applications of Arazzo:
+
+- Automating repetitive API workflows.
+- Adding API contract tests to CI/CD routines.
+- Keeping API documentation synchronized with actual API behavior.
+- Sharing described workflows across teams.
+- Using the open-source [@redocly/cli](https://www.npmjs.com/package/@redocly/cli) `respect` command to execute Arazzo workflows, inspect contract test results, and fix mismatches between the OpenAPI description and the actual API response.


Suggested change

This article shows how to use Respect, powered by Arazzo workflows, for API contract testing.

You will learn how to describe an API workflow, execute it with Redocly CLI, and use the results to find mismatches between an OpenAPI description and the real API behavior.

You will cover the following topics:

Practical applications of Arazzo:

- Automating repetitive API workflows.

- Adding API contract tests to CI/CD routines.

- Keeping API documentation synchronized with actual API behavior.

- Sharing described workflows across teams.

- Using the open-source [@redocly/cli](https://www.npmjs.com/package/@redocly/cli) `respect` command to execute Arazzo workflows, inspect contract test results, and fix mismatches between the OpenAPI description and the actual API response.

This article shows how to use Respect, powered by Arazzo workflows, for API contract testing.

You will cover the following topics:

- Automating repetitive API workflows.

- Adding API contract tests to CI/CD routines.

- Keeping API documentation synchronized with actual API behavior.

- Sharing described workflows across teams.

- Using the open-source Redocly CLI to execute Arazzo workflows, inspect contract test results, and fix mismatches between the OpenAPI description and the actual API response.

BTW, This is a lot of topics. Maybe split them into two articles?

All of those needed to cover flow with Auth, but we can make smaller about reusable Arazzo.

tatomyr · 2026-05-14T14:04:24Z

+Every Arazzo file begins with a version declaration.
+The latest stable version is `1.0.1`.


This is definitely redundant if you have basic familiarity with Arazzo. Either remove this or do add a separate guide on creating the Arazzo description itself.

I removed some, but maybe we can keep at least pointers started from workflow level?

tatomyr · 2026-05-14T14:09:12Z

+
+</details>
+
+In addition to the success criterion declared in the Arazzo file, Respect performed three additional checks automatically:


You've already said this here: https://github.com/Redocly/website/pull/149/changes#diff-90b9281218ab219b15a4758675d34ce45fe04dfde843f556a82dd8ade246a351R140. Please avoid repeating yourself.

Its more detailed description compare to

Respect also runs additional automatic checks based on the connected OpenAPI description (see the next section).

tatomyr · 2026-05-14T14:13:30Z

+  npm install @redocly/cli@latest -g
+  redocly respect products.arazzo.yaml --verbose


Let's not confuse readers with different running options. Let's use the npx ... way everywhere.

And that could be put into the Summary section anyway.

Lets keep the Summary small.

tatomyr · 2026-05-14T14:15:41Z

+After the schema is updated, the response body matches the documented contract.
+This demonstrates the core value of contract testing with Respect: when the API and its OpenAPI description drift apart, the workflow highlights the mismatch immediately.
+
+## Practical applications


I'm not even sure we have to explain practical cases in this article. I'd restrict that to saying that from now on it could be used in a CI/CD pipeline to check if there's no divergency between the docs and the server.

cc: @Redocly/technical-writers

redocly

marketing-site AI Review: 🟢 Completed

Reunite Bot has reviewed your changes and found 6 potential issue(s).

Note

Low Risk

This PR contains only documentation updates. There are no changes to the application code, ensuring there is no impact on runtime behavior or system stability.

Overview

Adds the first two articles for the "Respect practical example series" using Code Walkthroughs:

API Contract Testing: Demonstrates how to automate testing and verify API behavior using Arazzo workflows.
OAuth2 Authorization: Explains how to test OAuth2-secured API endpoints, focusing on reusable workflows and passing values between them.

Additionally, this PR adds the required _filesets (Arazzo and OpenAPI YAML specifications for the Redocly Cafe API) and updates learn/arazzo/sidebars.yaml to include the new guides in the navigation.

redocly · 2026-05-14T19:30:37Z

+The second step, `authorize-with-client_credentials`, calls `/oauth2/token` using the credentials returned by the previous step.
+
+In a production application, the `/callback` URL is usually implemented by the client application.
+In this example, the Redocly Cafe API provides the callback endpoint for demonstration purposes.


The comment about the /callback URL is misleading for the Client Credentials grant, as this flow is machine-to-machine and does not utilize a callback mechanism. This belongs to the Authorization Code grant.

redocly · 2026-05-14T19:30:38Z

+
+To follow the examples in this article, you need:
+
+- Basic familiarity with [Arazzo](https://redocly.com/learn/arazzo/what-is-arazzo).


Use a relative link ../what-is-arazzo.md instead of the absolute URL https://redocly.com/learn/arazzo/what-is-arazzo to ensure the link works correctly in local preview and self-hosted environments.

DmitryAnansky requested review from RomanHotsiy and tatomyr October 27, 2025 17:51

DmitryAnansky commented Oct 28, 2025

View reviewed changes

Comment thread learn/arazzo/arazzo-crud-practical-example.md Outdated

DmitryAnansky commented Oct 29, 2025

View reviewed changes

Comment thread learn/arazzo/arazzo-crud-practical-example.md Outdated

DmitryAnansky self-assigned this Oct 31, 2025

DmitryAnansky force-pushed the chore/respect-simple-usage-blog-post branch 2 times, most recently from 12e7702 to 9f2c0e4 Compare April 27, 2026 14:43

DmitryAnansky changed the title ~~WIP: respect usage article~~ docs(other): respect usage article Apr 29, 2026

DmitryAnansky requested review from a team April 29, 2026 12:06

DmitryAnansky commented Apr 30, 2026

View reviewed changes

tatomyr reviewed May 12, 2026

View reviewed changes

DmitryAnansky commented May 12, 2026

View reviewed changes

DmitryAnansky mentioned this pull request May 13, 2026

docs(other): alternative respect usage code walkthrough article #300

Merged

5 tasks

DmitryAnansky requested a review from a team May 14, 2026 14:04

tatomyr reviewed May 14, 2026

View reviewed changes

DmitryAnansky added 13 commits May 14, 2026 22:20

chore: arazzo crud example article

ea4481e

chore: change article style

da88174

docs: add draft of series 1 respect article

74a0ae3

docs(other): polish the text and examples

d74af47

docs(other): add oauth article

4682d9b

docs: update examples

a7b96ec

docs: fixing links and text update

3fc5a37

chore: change article structure

721dd5c

chore: text updates

f528e5a

chore: remove not critical descriptions

ce96ecb

docs: reduce example oas size

c1f2145

docs(other): alternative respect usage code walkthrough article (#300)

bf05093

chore: docs changes

238d21b

DmitryAnansky force-pushed the chore/respect-simple-usage-blog-post branch from dc03d73 to 238d21b Compare May 14, 2026 19:21

DmitryAnansky requested review from a team and tatomyr May 14, 2026 19:22

DmitryAnansky marked this pull request as ready for review May 14, 2026 19:23

redocly Bot reviewed May 14, 2026

View reviewed changes

chore: changes after review

dd4c528


		Arazzo provides a standard way to describe API workflows declaratively. Respect uses those workflows to run API contract tests against real API behavior.

		With this approach, teams can maintain API test coverage, detect documentation drift earlier, and share executable API workflows across engineering, QA, and documentation teams. No newline at end of file

		Every Arazzo file begins with a version declaration.
		The latest stable version is `1.0.1`.


		</details>

		In addition to the success criterion declared in the Arazzo file, Respect performed three additional checks automatically:

		npm install @redocly/cli@latest -g
		redocly respect products.arazzo.yaml --verbose


		To follow the examples in this article, you need:

		- Basic familiarity with [Arazzo](https://redocly.com/learn/arazzo/what-is-arazzo).

Conversation

DmitryAnansky commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

Uh oh!

Uh oh!

DmitryAnansky Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DmitryAnansky Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

redocly Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

redocly Bot May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

redocly Bot May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

DmitryAnansky commented Oct 27, 2025 •

edited

Loading

DmitryAnansky Apr 30, 2026 •

edited

Loading

DmitryAnansky Apr 30, 2026 •

edited

Loading

redocly Bot left a comment •

edited

Loading