lint configuration section is part of the Redocly configuration file.
It is used by the
bundle commands to control various options.
Modify (or create) the
.redocly.yaml file in the directory from which you are going to run the
When using our hosted Workflows product, the
.redocly.yaml file must be in the root of the repository.
Read about the
--config option to use other file names or locations.
From a high-level, there are a few sub-sections.
lint: plugins: # This section is where you can import local plugins. # We don't support community plugins. # You don't need to import our built-in plugins and rules. # Omit this section if you don't have custom plugins. - './local-plugin.js' extends: # This section is where you choose the base configurations. # You may override specific settings in the subsequent sections. - recommended # This is the default (and built in) configuration. If it is too strict, try `minimal`. resolve: # Use this when you have external links in your definition that are not publicly accessible. # Not required for Redocly API registry links. # We recommend using environment variables for when possible. http: headers: - matches: https://api.example.com/v2/** name: X-API-KEY value: <direct value> envVariable: <name of env variable to be used as value> - matches: https://example.com/*/test.yaml name: Authorization value: <direct value> envVariable: <name of env variable to be used as value> preprocessors: # Preprocessors are rarely indicated -- avoid if possible. # This section can be omitted. rules: # Override any rules that are available from the extends configuration. # Severity options are "error", "warn" or "off". no-sibling-refs: error # Uses syntactic sugar to define the severity level of an option. # Alternative verbose configuration no-sibling-refs: severity: error # Some rules may have additional configuration options. Use the verbose configuration style in those cases. # This boolean parameter prefixes example overrides the default "prefixes". boolean-parameter-prefixes: severity: error prefixes: ['should', 'is', 'has'] decorators: # Decorators modify the the definition after validation is complete, only in the bundling process. # This section can be omitted if you don't use decorators. ...
This applies to the preprocessors, rules, and decorators subsections of the lint configuration.
This file excerpt shows utilizing syntactic sugar to control the problem severity.
The severity level options are:
lint: extends: - recommended rules: boolean-parameter-prefixes: warn no-unused-components: error
When using the short syntax, you're unable to configure additional options for any given rule. Not all rules have additional options. See the rules documentation for more information. This is exactly the same as the settings above.
lint: extends: - recommended rules: boolean-parameter-prefixes: severity: warn no-unused-components: severity: error
In this example, we define additional rule options for the
lint: extends: - recommended rules: boolean-parameter-prefixes: severity: warn prefixes: ["can", "has", "is", "should"] no-unused-components: severity: error
To know which rules support options, please read the built-in rules documentation.
If you write custom rules, you may create rules that accept additional configuration options as well. Be sure to document those options for your users.
Redocly OpenAPI CLI supports versions 2 and 3 of OpenAPI. However, you may need to configure different rules based on the version. You can do that by using additional configuration sections.
lint: extends: - recommended rules: boolean-parameter-prefixes: warn no-unused-components: error oas2Rules: no-unused-components: off oas3_0Rules: boolean-parameter-prefixes: error
In this example, the OpenAPI specification version is identified.
If it is version 2 (formerly known as Swagger), it will prioritize the
If not defined, it will fall back to the
If it is version OpenAPI 3.0, it will prioritize the
If not defined, it will fall back to the
Read about our built-in rules.
The OpenAPI specification supports $refs in some of the objects. In practice, different tools and implementations of the OAS, as well as API definition authors, may use or even require $refs in unsupported places.
Starting with version
beta-30, OpenAPI CLI automatically resolves all $refs by default, even in places where they are not allowed by the specification. This includes primitive values like
string (e.g. in
description fields) and examples.
To disable resolving $refs in examples, use the
doNotResolveExamples configuration option in the
lint section of
.redocly.yaml. This does not affect $ref resolution in other parts of the API definition.
lint: doNotResolveExamples: true extends: - recommended rules: (...)
Redocly will automatically resolve any API registry link or public URL. However, you may want to resolve links that are not API registry links or publicly accessible.
resolve section to accomplish that.
Currently, OpenAPI CLI only supports
http headers. Only one
http header per URL is supported in the
It should be structured like this:
lint: resolve: http: headers: - # header configuration
Then, add your header definitions.
|matches||Glob match against the URL.||
|name||HTTP header name.||
|value||The value of the header. Mutually exclusive with
|envVariable||The name of the environment variable that contains the value of the header. Mutually exclusive with
Here is a structured example:
lint: resolve: http: headers: - matches: https://api.example.com/v2/** name: X-API-KEY envVariable: SECRET_KEY - matches: https://example.com/*/test.yaml name: Authorization envVariable: SECRET_AUTH
The first match will win in the event that a URL matches multiple patterns. Therefore, only the header from the first match will be used in the request.