Configuration file

Purpose

The configuration file controls configuration options of the CLI tool. It may be passed as metadata to the API registry which can then subsequently be used to build the docs.

Filename and location

The CLI tool will search the current working directory for a configuration file named .redocly.yaml.

File format

The configuration file is expected to be in YAML format.

The contents of the YAML are according to the following structure:

Copy
Copied
apiDefinitions:
# A set of named keys and values of entrypoints to OpenAPI definitions.
# Example:
  petstore: ./openapi/openapi.yaml
  caretaker: ./openapi/caretaker.yaml

lint:
# The lint command options

region: eu
# Configuration for optional AWS region selection when logging into Redocly services.

resolve:
# Configuration for resolving external links in your definition that are not publicly accessible.
# Not required for Redocly API registry links.

referenceDocs:
# The API reference docs options, including theme options.

registry:
# The API registry options

# future products may be configured by extending this file

apiDefinitions

The apiDefinitions section's purpose is to define one or more entrypoints to your OpenAPI 3 definitions. Redocly supports both multi-file definitions and multiple (multi-file) definitions.

This section is optional.

The validation command uses the apiDefinitions for providing shortcuts to referencing the definition.

Based on the example .redocly.yaml file above, here is an example usage:

Copy
Copied
openapi-cli lint petstore caretaker

In addition, it allows for running the command which will apply to all APIs defined:

Copy
Copied
openapi-cli lint

lint

The lint section's primary purpose is to define options for the lint and bundle commands. You may also import plugins and extends their configurations.

Read more about the lint configuration section.

region

For optimized performance or for compliance purposes, you can specify which region to use when logging into Redocly services (such as the API registry). Supported regions are us (used by default) and eu.

You should log into the region that corresponds to your Redocly Workflows organization. If you're a member of multiple organizations in different regions, it's technically possible to log into two different regions at the same time, but it's neither the most common nor the recommended use-case.

Every supported region uses its own domain.

RegionDomain
usapi.redoc.ly
euapi.eu.redocly.com

To configure which domain will be used, you can use any of the following:

  • the REDOCLY_DOMAIN environment variable
Copy
Copied
export REDOCLY_DOMAIN={domain}
  • the --region option with login and push commands

openapi login --region=eu

  • the region top-level property in the .redocly.yaml configuration file
Copy
Copied
apiDefinitions:
  main: ./openapi.yaml
region: eu
lint:
  extends: []

resolve

Redocly will automatically resolve any API registry link or public URL in your API definitions. However, you may want to resolve links that are not API registry links or publicly accessible. To accomplish that, add the resolve section to the configuration file.

OpenAPI CLI only supports http headers. Only one http header per URL is supported in the resolve section.

We recommend using environment variables whenever possible.

Resolving external links

The resolve section should be structured like this:

Copy
Copied
resolve:
  http:
    headers:
      - # header configuration

The headers section supports fields listed in the following table.

PropertyDescriptionExamples
matchesGlob match against the URL.https://api.example.com/** or https://api.example.com/*.json
nameHTTP header name.Authorization or X-API-KEY
valueThe value of the header. Mutually exclusive with envVariable.123-abc
envVariableThe name of the environment variable that contains the value of the header. Mutually exclusive with value.SECRET_KEY

Here is a structured 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 will win in the event that a URL matches multiple patterns. Therefore, only the header from the first match will be used in the request.

referenceDocs

The referenceDocs section configures features (availability and options) and theming (style, fonts, colors).

There are two products: Redoc Community Edition (CE), and Redocly API reference docs. Reference docs supports all configuration options from Redoc Community Edition plus a set of premium options.

Find the full list of supported options on the Reference docs configuration page.

registry

The registry section is reserved for future API registry features.

Read more about the registry section.

Schema reference

Array of objects non-empty

A map of aliases and the source of the API definitions. Especially useful for managing multiple API definitions.

object

A set of configurations to lint and decorate your APIs used when the lint and bundle commands execute.

object

Use this when you have external links in your definition that are not publicly accessible (except for Redocly API registry links). We recommend using environment variables where possible.

object

These configurations are used when previewing or building the docs.