Configure linting rules

Configure the rules for API linting in the redocly.yaml configuration file.

You can add rules, change their severity, or turn them off completely. Some rules support additional configuration.

You can also provide per-format or even per-API rule configuration. Use these approaches when your different types of API, or individual APIs, have different linting requirements.

Simple rule configuration

The following example shows rules configured in redocly.yaml with short syntax using the format rule-name: {severity}, where {severity} is one of error, warn or off:

rules:
  operation-operationId: warn

Some rules support additional configuration options. The following example shows the more verbose format where the severity setting is added alongside other settings:

rules:
  path-excludes-patterns:
    severity: error
    patterns:
      - ^\/fetch
      - ^\/v[0-9]

Check the documentation for each rule to see if it supports additional configuration.

Per-API configuration

You can set different rules for individual APIs by adding a rules object under each API in apis.

rules:
  operation-operationId: error
apis:
  museum:
    root: ./apis/museum.yaml
    rules:
      info-license: warn
  tickets@beta:
    root: ./apis/tickets.yaml
    rules:
      info-license: error
      operation-operationId-url-safe: error
      operation-operationId-unique: error

Each API picks up the settings that relate to it and gets linted accordingly.

Per-API configuration with configurable rules

You can use configurable rules for individual APIs. In the following example, UserApi@1 has a configurable rule defined. This rule applies only to UserApi@1.

extends:
  - recommended

apis:
  partnerApi@1:
    root: partners.yaml
    rules:
      no-server-trailing-slash: off
      operation-operationId: off

  newsletter@3:
    root: /absolute/path/to/folder/openapi.yaml
    extends:
      - minimal
    rules:
      no-server-trailing-slash: off

  UserApi@1:
    root: users.yaml
    rules:
      no-server-trailing-slash: off
      operation-operationId: warn
      assert/version-semver:
        subject:
          type: Info
          property: version
        assertions:
          pattern: /1.[0-9]\.[0-9]/
        message: API version must be in SemVer format, no major version release

Resources

• Learn more about rules and rulesets.
• Check the list of built-in rules.