Redocly configuration file
The Redocly configuration file is used by Redocly CLI and other Redocly apps to control their behavior — from the strictness of the lint
command, to how Redocly renders your docs.
- Workflows uses it in the API registry to manage your APIs and control advanced features like region and link resolution.
- Workflows and on-premise tools use it to apply your features and theme when building API docs.
- Redocly's VS Code extension uses it for linting criteria, to apply custom settings for live documentation previews, and to identify the path API definition root files.
Filename, location, and format
The Redocly configuration file must be named either redocly.yaml
or .redocly.yaml
.
It must be located in the root of your project directory, and it must be in the YAML format.
If you cloned the openapi-starter
project, this is already set up for you.
Redocly CLI searches for the configuration file in the working directory.
warning
If you have a redocly.yaml
and a .redocly.yaml
file in the same directory, Redocly shows a warning in the output and ask you to choose one file.
File structure
Fixed properties
organization | string Stores your Redocly Workflows organization ID that the To find the organization ID:
For example, if the URL is |
extends | Array of strings Inherit configurations. In case of conflict, priority goes to configurations further down the list. Finally, explicit declarations inline takes precedence over configurations inherited through the |
plugins | Array of strings <path> Import any local filesystem plugins (e.g. |
object (APIs object) Lets you configure one or more API definition files. This gives you the flexibility to reference specific files in commands, and configure each file at a granular level. | |
object (Preprocessors object) Change the severity level of any preprocessors in your extended configurations. Preprocessors run first during | |
object (Rules object) Change the severity level of any rules in your extended configurations. Some rules may also receive additional configurations. Rules run during the | |
object Used to enable or disable decorators. Decorators run during the | |
object | |
region | string Default: "us" Sets the region used for the |
object All API registry links and public URLs in your API definitions automatically resolve. If you want to resolve links that are neither API registry links nor publicly accessible, include this object to add an HTTP request header. Use environment variables where possible. |
Example
organization: testing_redocly
extends:
- recommended
apis:
core@v2:
root: ./openapi/openapi.yaml
rules:
no-ambiguous-paths: error
external@v1:
root: ./openapi/external.yaml
labels:
- external
theme:
openapi:
hideLogo: true
theme:
openapi:
schemaExpansionLevel: 2
generateCodeSamples:
languages:
- lang: curl
- lang: Python
extends
list
Use extends
to list built-in configurations and other configuration files as the base settings.
If you don't override this base configuration, it is used for all APIs specified in your configuration file.
If you don't have a Redocly configuration file, Redocly CLI automatically uses the recommended
configuration.
To override the default settings, you can either configure different settings for specific rules in the rules
object, or create your own configuration files and reference them in the extends
list.
Important
The previous behavior (automatically defaulting to the recommended
configuration) was deprecated since v1.0.0-beta.113
.
The extends
field has to be explicitly defined in the main configuration file for any extended configuration to apply.
The extends
list is structured as an array of strings.
It supports the following types of values:
- Built-in configuration name (
minimal
orrecommended
) - A plugin's registered configuration name
- Path or URL to another Redocly configuration file
When providing values as URLs, they must be publicly accessible.
extends:
- built-in-configuration-name
- local-plugin-name/configuration-name
- ./path/to/another/redocly-configuration.yaml
- https://url-to-remote/redocly.yaml
Nested configuration
Other configuration files linked in the extends
list of your main Redocly configuration file may contain their own extends
list.
Custom plugins can't contain the extends
list because recursive extension is not supported in that case.
The following examples illustrate configuration nesting with multiple configuration files.
extends:
- custom.yaml
extends:
- nested.yaml
rules:
tags-alphabetical: error
paths-kebab-case: warn
rules:
path-parameters-defined: error
tag-description: warn
Priority and overrides
In case of conflict, individual API settings specified in the apis
object always override settings globally specified.
Redocly CLI applies the extends
configuration in the order in which items are listed, from top to bottom.
The further down an item appears, the higher its priority.
In case of conflicting settings, content in the rules
and decorators
objects always overrides any content in the extends
list.
In the following example, the rules
object and another configuration file in the extends
list configure the same rule (tags-alphabetical
).
Due to the conflict, priority goes to the inline rules
over the extends
list, and the tags-alphabetical
has a resulting severity level of error
.
extends:
- custom.yaml
rules:
tags-alphabetical: error
paths-kebab-case: warn
rules:
tags-alphabetical: warn
path-parameters-defined: warn
The same approach applies within the extends
list.
If you have multiple configurations that try to configure the same rule, only the setting from the last configuration in the list applies.
In the following example, Redocly CLI uses the setting for the conflicting tags-alphabetical
rule from the testing.yaml
file, because that file is further down in the extends
list.
This means you can control the priority of configurations by reordering them in the extends
list, and override all lint configurations (custom and built-in) by specifying individual rule settings in the rules
object.
extends:
- custom.yaml
- testing.yaml
rules:
tags-alphabetical: warn
paths-kebab-case: warn
rules:
tags-alphabetical: error
path-parameters-defined: warn
plugins
list
Use this list to import local plugins. If you don't have any custom plugins, omit this list.
To prevent malicious code execution, custom plugins can't be imported from URLs, only from local files. Find more information on the Configs in plugins page.
- type:
array of strings
Examples
plugins:
- './local-plugin.js'
plugins:
- './local-plugin.js'
- './another-local-plugin.js'
apis
object
The apis
object is used to configure one or more APIs.
Every API in the object is identified by its name and version in the format name@version
.
The version is optional, and when not provided, Redocly apps interpret it as latest
by default.
Every name@version
combination listed in the object must be unique.
For every API listed in the object, you must provide the path to the OpenAPI definition using the root
property.
If rules
, decorators
, or preprocessors
aren't defined for an API, root settings are used.
If rules
, decorators
, or preprocessors
are defined for an API, its settings apply together with the root configuration.
If per-API and root settings modify the same properties, per-API settings overrides root settings.
Patterned properties
additional property | object (API object) non-empty Specifies the name and version of an API associated with the root API definition with the pattern | ||||||||||||||||||||||||||||||
|
Example
apis:
name@version:
root: ./openapi/openapi.yaml
labels:
- production
theme:
openapi: {}
Important
Per-API configurations take priority over global settings.
Some of the Redocly CLI commands, such as the lint command, use the API names from the apis
object as shortcuts for referencing API definitions.
You can tell the lint
command to validate specific API definitions by using their names from the apis
object, like in the following example:
redocly lint core@v2
On the other hand, if you run the command without specifying any aliases, it applies to all API definitions listed in the apis
object:
redocly lint
theme object
The theme
object configures OpenAPI features, mock server features, and others.
mockServer object
You can apply mockServer
to individual APIs as well as at the root (default) level.
In case of conflict, API takes priority.
The API registry supports the mock server feature and allows project owners to enable it for all branches per API version. When the mock server is enabled for an API, you can send test requests to it from any API client.
The mockServer
object is a property of the theme
object and allows additional configuration of the mock server behavior.
This object is optional.
Fixed properties
errorIfForcedExampleNotFound | boolean Default: false You can force specific examples to appear in the response by adding the optional |
strictExamples | boolean Default: false By default, the mock server automatically enhances responses with heuristics, such as substituting response fields with request parameter values. If set as |
openapi object
The openapi
object is a property of the theme
object and configures features and theming for API documentation generated from OpenAPI definitions.
If you need to apply different theming and functionality to individual APIs, add the theme openapi
property to the appropriate API in the apis
and theme
object, and use the same options as the global openapi
object.
Find the full list of supported options on the Reference docs configuration page.
resolve object
Redocly automatically resolves any API registry link or public URL in your API definitions.
If you want to resolve links that are neither API registry links nor publicly accessible, set the resolve
object in your configuration file.
Redocly CLI supports one http
header per URL.
Fixed properties
doNotResolveExamples | boolean Default: false You can stop | ||||||||||||
object Description of URL pattern matches and the corresponding headers to use when resolving references. | |||||||||||||
|
Example
Here is an example for adding header definitions:
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 takes priority when a URL matches multiple patterns. Therefore, only the header from the first match is used in the request.