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.
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.

Alternative Code Walkthrough Version => #300

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:54:22Z

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


Let's add a link to this article from '../what-is-arazzo.md'?

tatomyr · 2026-05-14T13:57:13Z

+You will learn how to define reusable workflows in separate files, pass values between workflows, and use those values to authorize API requests.
+
+You will cover the following topics:
+
+Practical applications of Arazzo:


Suggested change

You will learn how to define reusable workflows in separate files, pass values between workflows, and use those values to authorize API requests.

You will cover the following topics:

Practical applications of Arazzo:

You will cover the following topics:

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?

tatomyr · 2026-05-14T14:01:08Z

+Whichever approach you choose, validate the Arazzo file with Redocly CLI:
+
+```bash
+npx @redocly/cli@latest lint redocly-cafe-api.arazzo.yaml


Suggested change

npx @redocly/cli@latest lint redocly-cafe-api.arazzo.yaml

npx @redocly/cli lint redocly-cafe-api.arazzo.yaml

Let's save some space...

tatomyr · 2026-05-14T14:02:52Z

+npx @redocly/cli@latest lint redocly-cafe-api.arazzo.yaml
+```
+
+```bash


I'd not put several bash sections one after another. Either add a screenshot or just say something like this:

The tool will let you know that the description is valid.

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.

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.

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

+
+## Fix the schema
+
+In `redocly-cafe-api.yaml`, change `MenuItemList` from an `array` to an `object` with `object`, `page`, and `items` properties so the schema matches the response the API actually returns:


Let's link this as a step to redocly-cafe-api.yaml's MenuItemList so we can see the difference between the schemas.

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.

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.

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 from c28f30f to 12e7702 Compare April 27, 2026 14:42

DmitryAnansky added 2 commits April 27, 2026 17:43

chore: arazzo crud example article

d34a5f5

chore: change article style

9f2c0e4

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

docs: add draft of series 1 respect article

7031361

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

docs(other): polish the text and examples

ff0fb79

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

DmitryAnansky added 3 commits April 29, 2026 18:11

docs(other): add oauth article

66b7723

docs: update examples

a99eb3e

docs: fixing links and text update

1b33246

DmitryAnansky commented Apr 30, 2026

View reviewed changes

chore: change article structure

b3f728f

tatomyr reviewed May 12, 2026

View reviewed changes

DmitryAnansky commented May 12, 2026

View reviewed changes

DmitryAnansky added 3 commits May 12, 2026 18:33

chore: text updates

13b8672

chore: remove not critical descriptions

2ab70bd

docs: reduce example oas size

6bd740b

DmitryAnansky mentioned this pull request May 13, 2026

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

Merged

5 tasks

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

3f94d45

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

tatomyr reviewed May 14, 2026

View reviewed changes


		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


		To follow the examples in this article, you need:

		- Basic familiarity with [Arazzo](../what-is-arazzo.md).

	npx @redocly/cli@latest lint redocly-cafe-api.arazzo.yaml
	npx @redocly/cli lint redocly-cafe-api.arazzo.yaml

		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:


		## Fix the schema

		In `redocly-cafe-api.yaml`, change `MenuItemList` from an `array` to an `object` with `object`, `page`, and `items` properties so the schema matches the response the API actually returns:

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

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

DmitryAnansky commented Oct 27, 2025 •

edited

Loading

DmitryAnansky Apr 30, 2026 •

edited

Loading

DmitryAnansky Apr 30, 2026 •

edited

Loading