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: Log into Workflows. Access the API registry page. In your browser's address bar, find the page URL. 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`.
	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 `lint` and `bundle` commands behave.
	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
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 {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).
lint	object Configures linting options for the specified API. Supports the same format and options as the global `lint` object. API-level configuration will always override global configuration.
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
    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:

Copy

Copied

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:

Copy

Copied

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

plugins

Array of strings <path>

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

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

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. Redocly has over 40 built-in rules you can configure. Some are highly configurable, including assertions. For further customization, you can create custom plugins with custom rules.

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.

Example

Copy

Copied

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 `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 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.

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.