Redocly / redocly-cli

⚒️ Redocly CLI makes OpenAPI easy. Lint/validate to any standard, generate beautiful docs, and more.
https://redocly.com/docs/cli/
MIT License
907 stars 137 forks source link

Support per-format rulesets #1724

Open lornajane opened 1 week ago

lornajane commented 1 week ago

Is your feature request related to a problem? Please describe.

When I specify a ruleset in extends, such as recommended, it applies to all formats. I want to be able to apply recommended for OpenAPI and minimal for AsyncAPI.

Describe the solution you'd like

I'm actually not sure what would make sense here, since extends is an array. I'm open to suggestions and we should consider this alongside proposed changes in #1723 so they make sense together.

Per-format sections could work? Like the per-api sections, but different?

openapi-31:
  extends:
    - recommended
    - my-super-rules.yaml
  rules:
    security-defined: error

Describe alternatives you've considered

Changing extends completely to be an object.

extends:
  all:
    - minimal
  openapi-31:
     - recommended
  arazzo-10:
    - recommended-strict
    - spot

Another alternative:

From a conversation with @DmitryAnansky and @tatomyr about multi-format linting features.

tatomyr commented 1 week ago

When I specify a ruleset in extends, such as recommended, it applies to all formats.

Please note that it applies the rules according to the specification. For example, oas3_0Rules are applied only to OAS 3.0 API descriptions and so on.

tell users who lint multiple formats not to use extends at all but to use the per-format rules sections and provide copy/paste versions of our built in rulesets for each format

This is what I'd expect. Well, not exactly, but I'd expect to extend rules from something (either recommended, minimal, or a custom ruleset, e.g. defined in our cookbook), and then adjusting the particular rules severities. They can adjust separate rules severity for different specifications like this:

extends: 
- minimal
async2Rules:
  ...
oas3_1Rules:
  ...

If they want to reuse the same configuration later, they can simply extend from their new config.