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 will search 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 apps will show 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 |
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 Lets you set rules and decorators that control how the | |
object Lets you toggle features that control how mock servers behave. | |
features.openapi | object Configuration options supported by Redocly for rendering OpenAPI into web pages. Used when previewing or building the docs. See the list of options supported. |
region | string Default: "us" Sets the region used for the |
object All API registry links and public URLs in your API definitions will 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
apis:
core@v2:
root: ./openapi/openapi.yaml
lint:
rules:
no-ambiguous-paths: error
external@v1:
root: ./openapi/external.yaml
labels:
- external
features.openapi:
hideLogo: true
lint:
extends:
- recommended
features.openapi:
schemaExpansionLevel: 2
generateCodeSamples:
languages:
- lang: curl
- lang: Python
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.
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
lint: {}
features.openapi: {}
Important
Not all lint
options are supported in per-API configuration.
Consult the table below to understand how each configuration object applies to your APIs.
Configuration object | Per-API support | Behavior |
---|---|---|
lint.extends | ❗ | API settings override global settings. |
lint.rules | ✅ | API and global settings merge. In case of conflict, API takes priority. |
lint.decorators | ✅ | API and global settings merge. In case of conflict, API takes priority. |
lint.preprocessors | ✅ | API and global settings merge. In case of conflict, API takes priority. |
lint.plugins | ❌ | Available in global configuration only. |
features.openapi | ✅ | API and global settings merge. In case of conflict, API takes priority. |
features.mockServer | ✅ | API and global settings merge. In case of conflict, API takes priority. |
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 will apply to all API definitions listed in the apis
object:
redocly lint
lint object
The lint
object's primary purpose is to define options for the lint
and bundle
commands.
You may also import plugins and extends their configurations.
Fixed properties
doNotResolveExamples | boolean Default: false You can stop | ||
plugins | Array of strings <path> Import any local filesystem plugins (e.g. | ||
extends | Array of strings Inherit lint configurations. In case of conflict, priority goes to configurations further down the list. Finally, explicit declaration of any rules inline takes precedence over configurations inherited through the | ||
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 | |||
|
Example
lint:
extends:
- recommended
rules:
no-ambiguous-paths: error
decorators:
remove-x-internal: on
features.mockServer object
You can apply features.mockServer
to individual APIs as well as at the global level.
Option | Per-API support | Behavior |
---|---|---|
features.mockServer | ✅ | API and global settings merge. 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 features.mockServer
object 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 |
features.openapi object
The features.openapi
object 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 features.openapi
property to the apis
section, and use the same options as the global features.openapi
.
Find the full list of supported options on the Reference docs configuration page.
resolve object
Redocly will automatically resolve 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
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 will be used in the request.