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

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:

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

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

Example output:

[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

openapi lint --format=stylish

Example output:

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.

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.

< ... 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.

openapi lint --generate-ignore-file

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

This command will overwrite an existing 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.
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.

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.

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.

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