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
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.
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]
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
entrypoints argument can also use any glob format supported by your file system (e.g.
openapi lint ./root-documents/*.yaml).
lint command supports two output formats:
codeframe. Choose which format to use with the optional
The default format is
openapi lint --format=codeframe ## equivalent to: openapi lint
 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.
openapi lint --format=stylish
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 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 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
To generate ignore file for multiple definitions pass them as arguments:
openapi lint v1.yaml v2.yaml --generate-ignore-file
This command generates a file named
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.
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.
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.
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