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.

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 objectPer-API supportBehavior
lint.extendsAPI settings override global settings.
lint.rulesAPI and global settings merge. In case of conflict, API takes priority.
lint.decoratorsAPI and global settings merge. In case of conflict, API takes priority.
lint.preprocessorsAPI and global settings merge. In case of conflict, API takes priority.
lint.pluginsAvailable in global configuration only.
features.openapiAPI and global settings merge. In case of conflict, API takes priority.
features.mockServerAPI 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.

OptionPer-API supportBehavior
features.mockServerAPI 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.