docs: add arazzo rules documentation #1697

DmitryAnansky · 2024-08-29T15:46:27Z

What/Why/How?

Add documentation for Arazzo and AsyncAPI rules

Reference

Closes: #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

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

changeset-bot · 2024-08-29T15:46:31Z

⚠️ No Changeset found

Latest commit: 91b04e4

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 · 2024-08-29T15:47:44Z

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 · 2024-08-29T15:48:45Z

Coverage report

St.^❔	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.^❔	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 91b04e4

DmitryAnansky · 2024-08-30T15:02:33Z

docs/rules/recommended.md

@@ -27,6 +27,12 @@ Errors:
 - [security-defined](./security-defined.md)
 - [spec-components-invalid-map-name](./spec-components-invalid-map-name.md)
 - [spec](./spec.md)
+- [parameters-unique](./arazzo/parameters-unique.md)


It seems to me that we need a different structure for rules documentation.
The current version does not diverse OAS rules from AsyncAPI and Arazzo rules.
It's easy to be confused and mix spec-specific rules without checking rule details.

cc: @lornajane , @tatomyr

I agree. Maybe groups like "OpenAPI", and "Arazzo".

Or separator labels.

Yes, definitely. I'll push some changes to this branch and try to make it easier to understand.

Mmmm, I added the ruleset-templates page with all the rulesets for all the formats listed. Maybe I should have split that information onto these existing minimal and recommended documentation pages though, does anyone have an opinion?

Updated to reflect only having documentation for per-API configuration and keeping the per-format information as an internal-only implementation detail for now.

docs/rules/spec.md

docs/rules/minimal.md

packages/core/src/rules/arazzo/index.ts

docs/guides/lint-asyncapi.md

jeremyfiel · 2024-09-03T15:15:14Z

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

docs/rules/arazzo/parameters-unique.md

DmitryAnansky · 2024-09-04T08:18:48Z

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

Thanks for creating the pages for each rule, this is a great start! I will do some copy editing (I'll just push the changes if you don't mind), and figure out how to structure the information for the different description formats, but I need a few more things from you @DmitryAnansky if possible:

answer the open questions on the PR, I can transfer the answer to all the pages where it's something that comes up repeatedly
add some words for each of the mermaid charts, I'm not sure what we're trying to express here
can we say what problem each rule solves? I think if I knew that, I could do the rest of the updates and then request your review.

docs/guides/lint-asyncapi.md

docs/rules/arazzo/parameters-unique.md

docs/rules/arazzo/requestBody-replacements-unique.md

docs/rules/minimal.md

lornajane · 2024-09-05T11:02:21Z

docs/rules/recommended.md

@@ -27,6 +27,12 @@ Errors:
 - [security-defined](./security-defined.md)
 - [spec-components-invalid-map-name](./spec-components-invalid-map-name.md)
 - [spec](./spec.md)
+- [parameters-unique](./arazzo/parameters-unique.md)


Yes, definitely. I'll push some changes to this branch and try to make it easier to understand.

docs/rules/spec.md

docs/rules/spot/parameters-not-in-body.md

docs/rules/arazzo/workflow-dependsOn.md

Co-authored-by: Adam Altman <[email protected]>

…per-api/per-format sections with examples

… refactor sidebar

…description format

…sidebars

lornajane · 2024-10-07T10:12:12Z

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!

adamaltman

We're going to have to discuss this offline. I'm not in agreement to move forward with this as it is.

adamaltman

I have quite a few issues and things to discuss.

adamaltman · 2024-10-07T12:05:05Z

docs/rules/arazzo/requestBody-replacements-unique.md

+            - target: name
+              value: 'new name'
+            - target: name
+              value: 'another name'


This example is invalid not because of duplicate targets, but because targets must be JSON Pointer or XPath. This is not.

Suggested change

- target: name

value: 'new name'

- target: name

value: 'another name'

- target: /name

value: 'new name'

- target: /name

value: 'another name'

adamaltman · 2024-10-07T12:05:17Z

docs/rules/arazzo/requestBody-replacements-unique.md

+            - target: name
+              value: 'new name'
+            - target: description
+              value: 'another description'


Suggested change

- target: name

value: 'new name'

- target: description

value: 'another description'

- target: /name

value: 'new name'

- target: /description

value: 'another description'

docs/rules/arazzo/sourceDescriptions-name-unique.md

docs/rules/arazzo/workflowId-unique.md

docs/rules/async/channels-kebab-case.md

adamaltman · 2024-10-07T13:17:02Z

docs/rules/spot/parameters-not-in-body.md

These should be in the Arazzo folder. There shouldn't be any rules specific to Spot. Spot uses Arazzo files with some specification extensions that can be validated.

adamaltman · 2024-10-07T13:17:41Z

docs/rules/spot/parameters-not-in-body.md

@@ -0,0 +1,69 @@
+# parameters-not-in-body
+
+Requires the `in` section inside `parameters` must not contain a `body`.


This rule doesn't make sense. We should fix Spot's support for parameters in body.

adamaltman · 2024-10-07T13:18:43Z

docs/rules/spot/version-enum.md

This is not a spot rule. This should be part of the Arazzo spec rule. This shouldn't be a separate rule.

Co-authored-by: Adam Altman <[email protected]>

…til further notice

DmitryAnansky added the No Changeset Needed label Aug 29, 2024

DmitryAnansky force-pushed the chore/add-arazzo-rules-docs branch from 0c39fee to 00baee1 Compare August 30, 2024 14:05

tatomyr changed the title ~~chore: add arazzo rules documentation~~ docs: add arazzo rules documentation Aug 30, 2024

DmitryAnansky commented Aug 30, 2024

View reviewed changes

docs/rules/spec.md Outdated Show resolved Hide resolved

DmitryAnansky commented Aug 30, 2024

View reviewed changes

docs/rules/minimal.md Show resolved Hide resolved

DmitryAnansky commented Aug 30, 2024

View reviewed changes

packages/core/src/rules/arazzo/index.ts Show resolved Hide resolved

DmitryAnansky commented Aug 30, 2024

View reviewed changes

docs/guides/lint-asyncapi.md Show resolved Hide resolved

adamaltman reviewed Sep 3, 2024

View reviewed changes

docs/rules/arazzo/parameters-unique.md Outdated Show resolved Hide resolved

adamaltman reviewed Sep 3, 2024

View reviewed changes

docs/rules/arazzo/parameters-unique.md Outdated Show resolved Hide resolved

lornajane reviewed Sep 5, 2024

View reviewed changes

docs/rules/arazzo/workflow-dependsOn.md Show resolved Hide resolved

DmitryAnansky force-pushed the chore/add-arazzo-rules-docs branch from 6d8960e to 7124c2a Compare September 10, 2024 08:50

lornajane force-pushed the chore/add-arazzo-rules-docs branch from 7124c2a to f84451f Compare October 3, 2024 08:08

DmitryAnansky and others added 11 commits October 7, 2024 09:57

chore: add arazzo rules documentation

cdb9222

chore: add arazzo rules documentation

c4de777

chore: document requestBody-replacements-unique rule

ba802b9

chore: document arazzo rules

09d0016

chore: document async rules

c59483d

chore: update links

fb35ae1

Apply suggestions from code review

866978a

Co-authored-by: Adam Altman <[email protected]>

docs: copyedit, remove diagrams and page slugs, update for accuracy

7b024e6

docs: add new rules to built-in rules page, add format grouping

f83e4c0

docs: expand on the rules configuration options for basic/configured/…

85f99fd

…per-api/per-format sections with examples

docs: add descriptions and sorting to the new format rules

f8a7bc2

lornajane added 6 commits October 7, 2024 09:57

docs: Split rules config to separate page, add missing rules to list,…

988785a

… refactor sidebar

docs: add copy/paste versions of ruleset configurations for each api …

5cf1a58

…description format

docs: fix a renamed rule and a stray ARAZZO label

5ca82e9

docs: run prettier

8478eac

docs: adjust rule example to be more obvious

9d18cb7

docs: update link

ce5d903

lornajane force-pushed the chore/add-arazzo-rules-docs branch from da1e434 to ce5d903 Compare October 7, 2024 08:57

docs: update AsyncAPI channel rules with more info, add all rules to …

3074a89

…sidebars

lornajane marked this pull request as ready for review October 7, 2024 10:11

lornajane requested review from a team as code owners October 7, 2024 10:11

lornajane requested review from adamaltman and tatomyr October 7, 2024 10:12

adamaltman requested changes Oct 7, 2024

View reviewed changes

lornajane and others added 2 commits October 8, 2024 11:11

Apply suggestions from code review

baaf09b

Co-authored-by: Adam Altman <[email protected]>

docs: remove mentions of the per-format rule configuration feature un…

00c91c0

…til further notice

DmitryAnansky mentioned this pull request Oct 18, 2024

feat: removed the type:none sourceDescriptions Arazzo extension #1773

Closed

5 tasks

DmitryAnansky and others added 3 commits October 18, 2024 17:20

chore: add sourceDescriptions-not-empty rule docs

b3f89f3

docs: Adjust design principles sections of Arazzo rules

47a7701

docs: Make vale happy

91b04e4

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add arazzo rules documentation #1697

docs: add arazzo rules documentation #1697

DmitryAnansky commented Aug 29, 2024

changeset-bot bot commented Aug 29, 2024 •

edited

Loading

github-actions bot commented Aug 29, 2024 •

edited

Loading

github-actions bot commented Aug 29, 2024 •

edited

Loading

DmitryAnansky Aug 30, 2024 •

edited

Loading

adamaltman Sep 4, 2024

adamaltman Sep 4, 2024 •

edited

Loading

lornajane Sep 5, 2024

lornajane Oct 4, 2024

lornajane Oct 18, 2024

jeremyfiel commented Sep 3, 2024

DmitryAnansky commented Sep 4, 2024 •

edited

Loading

lornajane left a comment

lornajane Sep 5, 2024

lornajane commented Oct 7, 2024

adamaltman left a comment

adamaltman left a comment

adamaltman Oct 7, 2024

adamaltman Oct 7, 2024

adamaltman Oct 7, 2024

adamaltman Oct 7, 2024

adamaltman Oct 7, 2024

		@@ -0,0 +1,69 @@
		# parameters-not-in-body

		Requires the `in` section inside `parameters` must not contain a `body`.

docs: add arazzo rules documentation #1697

Are you sure you want to change the base?

docs: add arazzo rules documentation #1697

Conversation

DmitryAnansky commented Aug 29, 2024

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

changeset-bot bot commented Aug 29, 2024 • edited Loading

⚠️ No Changeset found

github-actions bot commented Aug 29, 2024 • edited Loading

github-actions bot commented Aug 29, 2024 • edited Loading

Coverage report

Test suite run success

DmitryAnansky Aug 30, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adamaltman Sep 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeremyfiel commented Sep 3, 2024

DmitryAnansky commented Sep 4, 2024 • edited Loading

lornajane left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lornajane commented Oct 7, 2024

adamaltman left a comment

Choose a reason for hiding this comment

adamaltman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

changeset-bot bot commented Aug 29, 2024 •

edited

Loading

github-actions bot commented Aug 29, 2024 •

edited

Loading

github-actions bot commented Aug 29, 2024 •

edited

Loading

DmitryAnansky Aug 30, 2024 •

edited

Loading

adamaltman Sep 4, 2024 •

edited

Loading

DmitryAnansky commented Sep 4, 2024 •

edited

Loading