lint

Introduction

Redocly CLI can identify and report on problems found in OpenAPI or Arazzo descriptions. This helps you avoid bugs and make API or Arazzo descriptions more consistent.

The lint command reports on problems and executes preprocessors and rules. Unlike the bundle command, lint doesn't execute decorators.

Usage

redocly lint
redocly lint <apis>...
redocly lint [--max-problems=<n>] [--config=<path>] [--format=<value>]
redocly lint [--generate-ignore-file] [--help]
redocly lint --version

Options

Examples

Specify API

The lint command behaves differently depending on how you pass the API(s) to it, and whether the configuration file exists.

Pass API directly

redocly lint openapi/openapi.yaml

In this case, lint validates the API or Arazzo description(s) passed to the command. If you have no configuration file defined, the recommended ruleset is used. If you have extends or rules defined in redocly.yaml, those are used when linting.

The apis argument can also use any glob format supported by your file system. For example:

redocly lint ./root-documents/*.yaml

Pass API alias

Instead of full paths, you can use names listed in the apis section of your Redocly configuration file. The example redocly.yaml configuration file below shows an API alias core@v1 defined:

apis:
  core@v1:
    root: ./openapi/api-description.json

Use the alias with the lint command as shown:

redocly lint core@v1

In this case, after resolving the path behind the core@v1 name, lint validates the api-description.json file. For this approach, the Redocly configuration file is mandatory.

Lint all configured APIs

You can omit the apis argument completely when executing the lint command to check all APIs defined in the configuration file. Run redocly lint with no arguments to lint all defined APIs. An example redocly.yaml file is shown below:

apis:
  core@v1:
    root: ./openapi/api-description.json
  production:
    root: ./openapi/production.yaml
  sandbox:
    root: ./openapi/sandbox.yaml

Use custom configuration file

By default, the CLI tool looks for the Redocly configuration file in the current working directory. Use the optional --config argument to provide an alternative path to a configuration file.

redocly lint --config=./another/directory/config.yaml

Extend configuration

The --extends option allows you to extend the existing configuration. This option accepts one of the following values: minimal, recommended, or recommended-strict. Each of the values is a base set of rules that the lint command uses. You can further modify this set in cases when you want to have your own set of rules based on the existing one, including particular rules that cover your specific needs. For more details, see rulesets.

redocly lint --extends=recommended-strict

Specify output format

The standard codeframe output format works well in most situations, but redocly can also produce output to integrate with other tools.

Codeframe (default)

redocly lint --format=codeframe

This command lints the file and uses the default output format of codeframe. It has the same behavior as omitting the --format parameter. Here's an output example:

[1] museum-with-errors.yaml:19:7 at #/paths/~1museum-hours/get/operationIds

Property `operationIds` is not expected here.

Did you mean: operationId ?

17 | summary: Get museum hours
18 | description: Get upcoming museum operating hours
19 | operationIds: getMuseumHours
20 | tags:
21 |   -  Operations

Error was generated by the spec rule.

Note that the problems are displayed in the following format: file:line:column. For example, museum-with-errors.yaml:19:7.

Depending on the terminal emulator you use, it may be possible to directly click this indicator to edit the file in place.

Stylish

redocly lint --format=stylish

This command uses the stylish format to get a more condensed output that is useful for summarizing the linting results, as seen in the example below:

museum-with-errors.yaml:
  19:7   error    spec                   Property `operationIds` is not expected here.
  29:11  error    spec                   Property `require` is not expected here.
  16:5   warning  operation-operationId  Operation object should contain `operationId` field.

In this format, lint shows the file name, line number, and column where the problem occurred. However, the output is compressed and omits other contexts and suggestions.

JSON

redocly lint --format=json

It can be useful to get the output in JSON format to be processed by other tools. Using this command gets the following example output:

{
  "totals": {
    "errors": 2,
    "warnings": 1,
    "ignored": 0
  },
  "version": "1.7.0",
  "problems": [
    {
      "ruleId": "spec",
      "severity": "error",
      "message": "Property `operationIds` is not expected here.",
      "suggest": [
        "operationId"
      ],
      "location": [
        {
          "source": {
            "ref": "museum-with-errors.yaml"
          },
          "pointer": "#/paths/~1museum-hours/get/operationIds",
          "reportOnKey": true
        }
      ]
    },
    {
      "ruleId": "spec",
      "severity": "error",
      "message": "Property `require` is not expected here.",
      "suggest": [],
      "location": [
        {
          "source": {
            "ref": "museum-with-errors.yaml"
          },
          "pointer": "#/paths/~1museum-hours/get/responses/200/require",
          "reportOnKey": true
        }
      ]
    },
    {
      "ruleId": "operation-operationId",
      "severity": "warn",
      "message": "Operation object should contain `operationId` field.",
      "location": [
        {
          "source": {
            "ref": "museum-with-errors.yaml"
          },
          "pointer": "#/paths/~1museum-hours/get/operationId",
          "reportOnKey": true
        }
      ],
      "suggest": []
    }
  ]
}

Checkstyle

redocly lint --format=checkstyle

The lint command also supports the Checkstyle XML report format. Use this command to get the following standard format output to use with your other tools:

<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.3">
<file name="museum-with-errors.yaml">
<error line="19" column="7" severity="error" message="Property `operationIds` is not expected here." source="spec" />
<error line="29" column="11" severity="error" message="Property `require` is not expected here." source="spec" />
<error line="16" column="5" severity="warning" message="Operation object should contain `operationId` field." source="operation-operationId" />
</file>
</checkstyle>

Due to the limitations of this format, only file name, line, column, severity, and rule ID (in the source attribute) are included. All other information is omitted.

GitHub Actions

redocly lint --format=github-actions

The lint command also comes with support for a GitHub Actions specific formatting. Specify this output format to have any encountered problem annotated on the affected files.

::error title=spec,file=museum-with-errors.yaml,line=19,endLine=19,col=7,endColumn=7::Property `operationIds` is not expected here.
::error title=spec,file=museum-with-errors.yaml,line=29,endLine=29,col=11,endColumn=11::Property `require` is not expected here.
::warning title=operation-operationId,file=museum-with-errors.yaml,line=16,endLine=16,col=5,endColumn=5::Operation object should contain `operationId` field.

Markdown

Use markdown format output with the lint command to get a Markdown-ready output format. This output format is useful if you want to report the outcomes to a document, or use the information in a GitHub Job Summary.

Running the lint command with --format=markdown produces output like the following example:

## Lint: ./museum-with-errors.yaml

| Severity | Location | Problem | Message |
|---|---|---|---|
| error | line 42:11 | [spec](https://redocly.com/docs/cli/rules/spec/) | Must contain at least one of the following fields: schema, content. |
| error | line 44:11 | [spec](https://redocly.com/docs/cli/rules/spec/) | Property `type` is not expected here. |

Validation failed
Errors: 2

The output includes a formatted table, and links to any built-in rules that identified problems. An example is shown in the following screenshot.

Limit the displayed problems count

With the --max-problems option, you can limit the number of problems displayed in the command output. Here's an example command:

redocly lint --max-problems=20

If the number of detected problems exceeds the specified threshold, the remaining problems are hidden under the "spoiler message" that lets you know how many problems were hidden.

< ... 2 more problems hidden > increase with `--max-problems N`

Note that the default value is 100.

Generate ignore file

With this option, you can generate the .redocly.lint-ignore.yaml file to suppress error and warning severity problems in the output. You still receive visual feedback to let you know how many problems were ignored.

This option is useful when you have an API design standard, but have some exceptions to the rule (for example, a legacy API operation). It allows for highly granular control.

The following command runs lint and adds all the errors to an ignore file:

redocly lint museum-with-errors.yaml --generate-ignore-file

Here's the example output:

Generated ignore file with 3 problems.

The errors in the ignore file .redocly.lint-ignore.yaml are ignored when the lint command is run.

To generate an ignore file for multiple API descriptions, pass them as arguments:

redocly lint v1.yaml v2.yaml --generate-ignore-file

Example of an ignore file:

# This file instructs Redocly's linter to ignore the rules contained for specific parts of your API.
# See https://redoc.ly/docs/cli/ for more information.
museum-with-errors.yaml:
  spec:
    - '#/paths/~1museum-hours/get/operationIds'
    - '#/paths/~1museum-hours/get/responses/200/require'
  operation-operationId:
    - '#/paths/~1museum-hours/get/operationId'

The rule in the example is named spec, which indicates compliance with the OpenAPI spec. You can also manually add problems that should be ignored to specific rules.

Skip preprocessor or rule

You may want to skip specific preprocessors or rules upon running the command. Examples for each option are as follows:

redocly lint --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example

To learn more about preprocessors, rules, and decorators, refer to the custom plugins page.

Lint config file

The lint command also validates the configuration file. You may want to set severity level by using the --lint-config option. This option accepts one of the following values: warn,error,off. Default value is warn.

redocly lint --lint-config=off

Lint Arazzo description file

The lint command also validates The Arazzo description files. You can pass the Arazzo description file to the lint command as shown below:

redocly lint arazzo.yaml