5.3 KiB
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.
graph LR
preprocessors[Preprocessors]
rules[Rules]
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
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 .redocly.lint-ignore.yaml.
:::warning
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