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 push command uses to push API definition files to the API registry. If an organization ID is not passed explicitly in command-line arguments, push will look for it in redocly.yaml.

To find the organization ID:

  1. Log into Workflows.
  2. Access the API registry page.
  3. In your browser's address bar, find the page URL.
  4. The segment after app.redocly.com/org/ is the organization ID.

For example, if the URL is app.redocly.com/org/test_docs, the organization ID is test_docs.

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 extends feature. Built in configurations include recommended and minimal.

plugins
Array of strings <path>

Import any local filesystem plugins (e.g. ./local-plugins.js). Note that community plugins are not yet supported.

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 lint and bundle.

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 lint command after preprocessors. They run during the bundle command between preprocessors and decorators if the --lint option is used.

object

Used to enable or disable decorators. Decorators run during the bundle command after linting.

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 login and push commands. The eu region is limited to enterprise customers. Alternatively, set the environment variable REDOCLY_DOMAIN to the appropriate Redocly destination's domain (such as https://api.redocly.com).

Enum: "us" "eu"
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

Copy
Copied
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
    features.openapi:
      hideLogo: true

features.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 or recommended)
  • A plugin's registered configuration name
  • Path or URL to another Redocly configuration file

When providing values as URLs, they must be publicly accessible.

Copy
Copied
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.

Main redocly.yamlcustom.yamlnested.yaml
Copy
Copied
extends:
  - custom.yaml
Copy
Copied
extends:
  - nested.yaml
rules:
  tags-alphabetical: error
  paths-kebab-case: warn
Copy
Copied
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.

redocly.yamlcustom.yaml
Copy
Copied
extends:
  - custom.yaml
rules:
  tags-alphabetical: error
  paths-kebab-case: warn
Copy
Copied
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 will apply.

In the following example, Redocly CLI will use 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.

redocly.yamlcustom.yamltesting.yaml
Copy
Copied
extends:
  - custom.yaml
  - testing.yaml
Copy
Copied
rules:
  tags-alphabetical: warn
  paths-kebab-case: warn
Copy
Copied
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

Import a single pluginImport multiple plugins
Copy
Copied
plugins:
  - './local-plugin.js'
Copy
Copied
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, global settings are used. If rules, decorators, or preprocessors are defined for an API, its settings apply together with the global configuration. If per-API and global settings modify the same properties, per-API settings will override global 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 {name}@{version}. If the version is omitted, Redocly apps interpret it as 'latest' by default.

root
required
string

The path to the root API definition file of the specified API.

labels
Array of strings

Use it to assign one or more existing Redocly Workflows organization-wide labels to your APIs. You must have a Redocly Workflows account with an active organization, and add the top-level organization property to the configuration file. If you try to assign labels that don't already exist for your organization, Redocly apps will display a warning in the output and will only assign the existing labels (if any).

object (Preprocessors object)

Change the severity level of any preprocessors in your extended configurations. Preprocessors run first during lint and bundle.

additional property
string or object

List each preprocessor by name. For example, do-this-first.

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 lint command after preprocessors. They run during the bundle command between preprocessors and decorators if the --lint option is used.

additional property
string or Rule configuration object (object)

List each rule by name. For example, no-empty-servers.

object

Used to enable or disable decorators. Decorators run during the bundle command after linting.

additional property
string or Decorator configuration object (object)

List each decorator by name. For example, remove-x-internal.

features.openapi
object

Defines theming and functionality for an API definition. Supports the same format and options as the global features.openapi object. API-level configuration will always override global configuration.

features.mockServer
object

Defines mock server behavior for an API definition. Supports the same format and options as the global features.mockServer object. API-level configuration will always override global configuration.

Example

Copy
Copied
apis:
  name@version:
    root: ./openapi/openapi.yaml
    labels:
      - production
    features.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:

Copy
Copied
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:

Copy
Copied
redocly lint

features.mockServer object

You can apply features.mockServer to individual APIs as well as at the global 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 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 x-redocly-response-body-example header to your requests. If you pass an example ID that can't be found in the API definition, the mock server will return any other example unless errorIfForcedExampleNotFound is true. Then the mock server will return an error instead.

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 true, examples are returned in the response unmodified, and exactly how they are described in the OpenAPI definition.

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 appropriate API in the apis object, 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

doNotResolveExamples
boolean
Default: false

You can stop lint from resolving $refs in examples by setting this configuration option to true. This does not affect $ref resolution in other parts of the API definition.

object

Description of URL pattern matches and the corresponding headers to use when resolving references.

Array of objects non-empty
Array (non-empty)
matches
required
string

The URL pattern to match. For example, https://api.example.com/v2/** or https://example.com/*/test.yaml

name
required
string

The header name. For example, X-API-KEY.

value
string

The value of the header. Mutually exclusive with envVariable. We recommend to use envVariable instead for any secrets.

envVariable
string

The environment variable name which will be resolved and should contain the value. Mutually exclusive with value.

Example

Here is an example for adding header definitions:

Copy
Copied
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.