docs: add arazzo rules documentation

[DmitryAnansky]

What/Why/How?

Add documentation for Arazzo and AsyncAPI rules

Reference

Closes: https://github.com/Redocly/redocly-cli/issues/1691

Testing

Screenshots (optional)

Check yourself

• [ ] Code changed? - Tested with redoc/reference-docs/workflows (internal)
• [ ] All new/updated code is covered with tests
• [ ] New package installed? - Tested in different environments (browser/node)

Security

• [x] Security impact of change has been considered
• [x] Code follows company security practices and guidelines

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 91b04e4529dff922b8f268c9216d147133a12ce8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions[bot]]

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
redocly lint packages/core/src/benchmark/benches/rebilly.yaml	980.8 ± 16.6	951.2	1011.4	1.00
redocly-next lint packages/core/src/benchmark/benches/rebilly.yaml	1016.0 ± 17.2	989.8	1049.0	1.04 ± 0.02

[github-actions[bot]]

Coverage report

St.:grey_question:	Category	Percentage	Covered / Total
🟡	Statements	78.58%	4993/6354
🟡	Branches	67.24%	2063/3068
🟡	Functions	73.01%	825/1130
🟡	Lines	78.87%	4711/5973

Show new covered files 🐣

St.:grey_question:	File	Statements	Branches	Functions	Lines
🟢	... / sourceDescriptions-type.ts	100%	100%	100%	100%

Test suite run success

810 tests passing in 121 suites.

Report generated by 🧪jest coverage report action from 91b04e4529dff922b8f268c9216d147133a12ce8

[jeremyfiel]

sorry to give duplicate work but most of the arazzo defined rules in this pr are handled by the recently merged JSON Schema definition for Arazzo 1.0. It's currently in the 1.0.0-dev branch but is expected to be merged to main very soon.

https://github.com/OAI/Arazzo-Specification/pull/224/files#diff-c3b79a68b0d389644801b367021ceb2169c0a1afbdec651107b11605db4671c2

[DmitryAnansky]

sorry to give duplicate work but most of the arazzo defined rules in this pr are handled by the recently merged JSON Schema definition for Arazzo 1.0. It's currently in the 1.0.0-dev branch but is expected to be merged to main very soon.

https://github.com/OAI/Arazzo-Specification/pull/224/files#diff-c3b79a68b0d389644801b367021ceb2169c0a1afbdec651107b11605db4671c2

@jeremyfiel Thank you for your contribution, having an official JSON Schema is great and will be applied for generating types, but we'll use these rules to validate internal type mapping, as the JSON schema might not fully address some nested cases or apply entirely to the internally mapped types.

[lornajane]

Can I get some reviews on this, please? There's one open conversation about page structure but otherwise I am pretty happy with how this turned out and kudos to @DmitryAnansky for all the hard work - both on the feature and on the docs!

[DmitryAnansky]

Moved docs changes to https://github.com/Redocly/redocly-cli/pull/1819