lint

Redocly OpenAPI CLI can identify and report on problems found in OpenAPI definitions, with the goal of avoiding bugs and making APIs more consistent. The lint command reports on problems and executes preprocessors and rules. Unlike the bundle command, lint doesn't execute decorators.

Use custom rules, plugins, preprocessors, and the built-in rules to define your API design standards. Every rule is a plugin that can be added at runtime.

Preprocessors
Rules

lint usage

Copy
Copied
Positionals:
  entrypoints                                              [array] [default: []]

Options:
  --version               Show version number.                         [boolean]
  --help                  Show help.                                   [boolean]
  --format                Use a specific output format.
                        [choices: "stylish", "codeframe"] [default: "codeframe"]
  --max-problems          Reduce output to max N problems.
                                                         [number] [default: 100]
  --generate-ignore-file  Generate ignore file.                        [boolean]
  --skip-rule             Ignore certain rules.                          [array]
  --skip-preprocessor     Ignore certain preprocessors.                  [array]
  --config                Specify path to the config file.              [string]
  --extends               Override extends configurations (defaults or config
                          file settings).                                [array]

The command:

Copy
Copied
openapi lint openapi/openapi.yaml

This validates the specified entrypoint(s). If none are specified, lint validates all entrypoints listed in the apiDefinitions section of the .redocly.yaml file.

The entrypoints argument can also use any glob format supported by your file system (e.g. openapi lint ./root-documents/*.yaml).

Options

Format

The lint command supports two output formats: stylish and codeframe. Choose which format to use with the optional --format argument.

The default format is codeframe.

Codeframe format

Copy
Copied
openapi lint --format=codeframe
## equivalent to: openapi lint

Example output:

Copy
Copied
[1] resources/petstore-with-errors.yaml:16:3 at #/paths/~1pets?id

Don't put query string items in the path, they belong in parameters with `in: query`.

14 |   - name: pets
15 | paths:
16 |   /pets?id:
   |   ^^^^^^^^
17 |     get:
18 |       summary: List all pets

Error was generated by the path-not-include-query rule.

Notice the output shows the file:line:column of code. Depending on the terminal emulator you use, it may be possible to directly click this indicator to edit the file in place.

Stylish format

Copy
Copied
openapi lint --format=stylish

Example output:

Copy
Copied
openapi/core.yaml:
  183:5  error  spec  Property `nam` is not expected here.

It still shows the file name, line number and column. However, the output is compressed and omits other context and suggestions.

Max problems

With the --max-problems option, you can limit the amount of problems displayed in the command output.

Copy
Copied
openapi lint --max-problems 200

If the amount of detected problems exceeds the threshold you set, the remaining problems are hidden in the output, but a feedback message lets you know how many were hidden.

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

Generate ignore file

Generate an ignore file to suppress error and warning severity problems in the output. When ignored, there will still be some 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.

Copy
Copied
openapi lint --generate-ignore-file

To generate ignore file for multiple definitions pass them as arguments:

Copy
Copied
openapi lint v1.yaml v2.yaml --generate-ignore-file

This command generates a file named .redocly.lint-ignore.yaml.

warning

This command will overwrite an existing ignore file.

Example of an ignore file:

Copy
Copied
# 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.
openapi/core.yaml:
  spec:
    - '#/tags/23'
    - '#/tags/55'

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

Skip preprocessor

You may want to skip specific preprocessors upon running the command.

Copy
Copied
openapi lint --skip-preprocessor=discriminator-mapping-to-one-of,another-example

Learn more about preprocessors.

Skip rule

You may want to skip specific rules upon running the command.

Copy
Copied
openapi lint --skip-rule=no-sibling-refs,no-parent-tags

Learn more about rules.

Specify config file

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

Copy
Copied
openapi lint --config=./another/directory/file.yaml