Rules

All Redocly CLI rules are listed on this page.

To learn how to configure rules, read more about their configuration syntax.

Rules are roughly grouped by the OpenAPI object they apply to. The Special rules group contains rules that may apply to multiple objects or to the entire OpenAPI document.

Special rules

Info

Operations

Parameters

Paths

Requests, Responses, and Schemas

Servers

Tags

Rule configuration syntax

To change your settings for any given rule, add or modify its corresponding entry in your Redocly configuration file.

You can specify global settings in the top-level lint and rules object, or use per-API settings by adding a lint and rules object under each API in apis.

You can format each entry in the lint and rules object in one of the following ways:

  • Short syntax with single-line configuration rule-name: {severity} , where {severity} is one of error , warn or off . You can't configure additional rule options with this syntax.
Copy
Copied
apis:
  main:
    root: ./openapi/openapi.yaml
    styleguide:
      rules:
        specific-api-rule: warn
styleguide:
  rules:
    example-rule-name: error
  • Verbose syntax, where you can configure additional options for rules that support them.
Copy
Copied
apis:
  main:
    root: ./openapi/openapi.yaml
    styleguide:
      rules:
        specific-api-rule:
          severity: warn
styleguide:
  rules:
    example-rule-name:
      severity: error
      rule-option-one: value
      rule-option-two: value

Severity settings

Severity settings determine how the rule is treated during the validation process.

  • severity: error - if the rule is triggered, the output displays an error message and the API definition doesn't pass validation.
  • severity: warn - if the rule is triggered, the output displays a warning message. Your API definition may still be valid if no other errors are detected.
  • severity: off - disables the rule altogether. The rule is skipped during validation.

Recommended config

There are two built-in configurations:

  • minimal
  • recommended

The recommended configuration can be enabled by adding

Copy
Copied
styleguide:
  extends:
    - recommended

to the Redocly configuration file.

You may then override the severity for any specific rule in the rules object.

Here is the equivalent of the recommended configuration values:

Copy
Copied
    info-description: warn
    info-license: warn
    info-license-url: warn
    tag-description: warn
    no-path-trailing-slash: error
    no-ambiguous-paths: warn
    path-declaration-must-exist: error
    path-not-include-query: error
    path-parameters-defined: error
    operation-2xx-response: warn
    operation-4xx-response: warn
    operation-operationId: warn
    operation-summary: error
    operation-operationId-unique: error
    operation-operationId-url-safe: error
    operation-parameters-unique: error
    operation-security-defined: error
    no-unresolved-refs: error
    no-enum-type-mismatch: error
    spec: error
    no-invalid-media-type-examples:
      severity: warn
      disallowAdditionalProperties: true
    no-server-example.com: warn
    no-server-trailing-slash: error
    no-empty-servers: error
    no-example-value-and-externalValue: error
    no-unused-components: warn
    no-undefined-server-variable: error

Rule ideas

Redocly CLI supports assertions and custom rules. However, if you have an idea for a built-in rule you believe will benefit the greater API community, please open an issue in the Redocly CLI repository.