Migration guide: Redocly configuration file

The Redocly configuration file is used by multiple Redocly apps to help you control their behavior.

• Redocly CLI uses it as the central configuration file when working with your API definitions.
• Workflows uses it in the API registry to manage your APIs and control advanced features like region and link resolution.
• Reference uses it to apply your custom settings for API reference documentation (hosted and on-premise).
• VS Code extension uses it for linting criteria, to apply custom settings for live documentation preview, and to set API definition root files.

In the latest releases of these apps, we have implemented a new format of the configuration file. Our goal was to simplify its usage, improve the integration of Redocly apps, and standardize the way they interpret the configuration file.

We encourage all users to start using the new configuration file. Although still supported, the legacy configuration file is deprecated. You will receive warning messages in build logs if you decide to keep it.

This guide lists all changes, new options, and differences between the new and the legacy configuration file. The documentation has been updated to reflect these changes, and all examples in the documentation refer to the new configuration file.

Changes to the Redocly configuration file

Supported file names

You can now name the configuration file redocly.yaml or .redocly.yaml.

Previously, only the .redocly.yaml file name was supported, which sometimes caused issues because it was a hidden file.

Redocly apps don't have an order of precedence or a specific preference for either of the supported file names. They will use whichever configuration file is detected in your working directory or project root.

Multiple configuration files in the same directory are not allowed. If you have a redocly.yaml and a .redocly.yaml file in the same directory, Redocly apps will display a warning in the output and ask you to choose one file to use.

Changed properties

• Renamed apiDefinitions to apis .
• Previously, every API under apiDefinitions was identified by its definitionId or alias. Now, the APIs under apis are identified by their name and version in the format name@version . The version is optional, and when not provided, Redocly apps interpret it as latest by default. The API name and version from the configuration file are directly used by Redocly apps. This reduces the complexity of having arbitrary aliases as an extra layer between the API and Redocly apps.
• Previously, the alias mapped directly to the path of the OpenAPI definition (as a string value). Now, the name@version is an object that requires a separate root property to provide the path to the OpenAPI definition.
• Renamed referenceDocs to features.openapi . All supported configuration options and their format remain the same.

Compare these examples to understand the changes:

apis:
  main@v1:
    root: ./openapi/openapi.yaml
lint:
  rules:
    example-rule-name: error
features.openapi:
  pagination: section
  showConsole: true
  theme:
    menu:
      backgroundColor: '#fffff'

apiDefinitions:
  main: ./openapi/openapi.yaml
lint:
  rules:
    example-rule-name: error
referenceDocs:
  pagination: section
  showConsole: true
  theme:
    menu:
      backgroundColor: '#fffff'

New properties

Organization

A new top-level property called organization has been added to the configuration file. The organization property requires the organization ID of your Redocly Workflows organization.

To find the organization ID, log into Workflows and access the API registry page. In your browser's address bar, find the URL of the page. The path segment after app.redocly.com/org/ is your organization ID. For example, if the URL is app.redocly.com/org/test_docs, the organization ID is test_docs.

The organization property is only required in the configuration file if you're using the API registry and/or hosted Reference docs. It is not required for local Redocly CLI usage.

organization: test_docs
apis:
  main@v1:
    root: ./openapi/openapi.yaml
lint: []
features.mockServer: []
region: []
resolve: []
features.openapi: []
registry: []

apiDefinitions:
  main: ./openapi/openapi.yaml
lint: []
features.mockServer: []
region: []
resolve: []
referenceDocs: []
registry: []

Root

The apis section requires a new property called root to specify the path to the root OpenAPI definition file.

When setting up multiple APIs, every API listed in the configuration file must have its own root property and path.

apis:
  main@v1:
    root: ./openapi/openapi.yaml
  external@v2:
    root: ./openapi/external.yaml

apiDefinitions:
  main: ./openapi/openapi.yaml
  external: ./openapi/external.yaml

Labels

The apis section supports a new optional property called labels. You can use the labels property per each API listed in the configuration file. Its purpose is to assign one or more existing Redocly Workflows organization-wide labels to your APIs.

This means there are several prerequisites to using labels:

• you must have a Redocly Workflows account with an active organization;
• you must create the labels in your organization;
• you must use the organization property in your configuration file.

If you try to apply labels that don't already exist for your organization, Redocly apps will display a warning in the output. Any existing label(s) you used in the file will be applied.

organization: test_docs
apis:
  main@v1:
    root: ./openapi/openapi.yaml
    labels:
      - production
      - active
  external@v2:
    root: ./openapi/external.yaml
    labels:
      - external

Per-API configuration

The apis section supports optional lint and features.openapi sections per each API. This allows you to use different rules, decorators, and Reference docs configuration for different APIs.

If lint and features.openapi sections are not defined for an API, global configuration is used. If lint and features.openapi sections are defined for an API, their settings apply together with the global configuration. In case of conflict, per-API settings will override global settings.

There are two exceptions to that behavior:

• The lint.extends section, if defined for an API, overrides the global configuration entirely.
• The lint.plugins section is only supported in the global configuration.

Read more about per-API configuration in the Redocly configuration file docs.

organization: test_docs
apis:
  main@v1:
    root: ./openapi/openapi.yaml
    labels:
      - production
      - active
    lint:
      rules:
        no-identical-paths: warn
      decorators:
        hide-internal-apis: error
    features.openapi:
      disableSearch: true
      hideLogo: true
  external@v2:
    root: ./openapi/external.yaml
    labels:
      - external
    lint:
      rules:
        example-rule-name: off
    features.openapi:
      pagination: item
lint:
  rules:
    example-rule-name: error
features.openapi:
  pagination: section
  showConsole: true
  theme:
    menu:
      backgroundColor: '#fffff'

apiDefinitions:
  main: ./openapi/openapi.yaml
  external: ./openapi/external.yaml
lint:
  rules:
    example-rule-name: error
    no-identical-paths: warn
  decorators:
    hide-internal-apis: error
referenceDocs:
  pagination: section
  showConsole: true
  theme:
    menu:
      backgroundColor: '#fffff'

Other related changes

Because the Redocly configuration file is used by multiple products, their behavior has changed to make the best use of the new configuration file format.

More specifically:

• the Redocly CLI push command now supports simplified syntax;
• the API registry is now able to automatically pull information from the configuration file when adding a new API.

The following two sections provide more details on each change.

Redocly CLI push command

The following changes have been made to the Redocly CLI push command:

• entrypoint is now optional. Previously, it was required to provide either the path to the API definition or the alias from the configuration file to tell the command which API to work with. Now, the API name and version from the configuration file always directly match the destination API name and version in the registry, so there is no need to explicitly provide them.
• the organization ID component in the destination argument is now optional. If you want to omit it from the command, you must provide the organization ID as the value of the organization property in the configuration file. The push command uses the following order of precedence: first, it takes the organization ID from the command-line argument (if provided). If the organization ID is not provided explicitly, it takes it from the configuration file.
• branchName is now deprecated as a standalone argument. If you still want to specify a branch name in the command, you must use it in the format --branch branchName or -b branchName .

As a result, you can now use simplified push command syntax in several ways depending on what you set in the configuration file. The same syntax applies when using push to update existing APIs and when using push -u to upsert APIs.

1. openapi push

This approach will push all APIs listed in the apis section of the configuration file. You must specify your Workflows organization ID in the configuration file for this approach to work. APIs without an explicitly defined version are automatically pushed to @latest.

2. openapi push name@version

This approach will push the specified API and version from the apis section of the configuration file to the API registry. You must specify your Workflows organization ID in the configuration file for this approach to work.

3. openapi push orgID/name@version

This approach will push the specified API and version from the apis section of the configuration file to the Workflows organization matching the provided organization ID.

Note that you can still use all optional arguments to explicitly push or upsert any API definition file to any organization, name, version and branch:

openapi push openapi.yaml @orgID/name@version --branch devel

API registry settings

When adding a new API to the registry, the first step is now to select the source of your API definition. Previously, the first step was to set the name for your API definition.

If your source contains the new Redocly configuration file with specified organization ID, API name and/or version, the Workflows dialog automatically pulls the name and version and sets them as the default. If you have only provided the name, but not the version, the dialog sets latest as the default version.

If you have specified any labels for your API in the new configuration file, and if they match the existing labels in your Workflows organization, the Workflows dialog automatically identifies and assigns them to your API in the registry.

Use the new configuration file

The following changes are required to start using the new configuration file.

1. Rename apiDefinitions to apis .
2. In the apis section, make sure to set the name and path to the root API definition for each API. The version is optional.

apis:
  name@version:
    root: path/to/root/definition.yaml

3. Rename referenceDocs to features.openapi .
4. If you're using the API registry or hosted Reference docs, add the organization property to the top level of the configuration file. Provide your Workflows organization ID as its value.

organization: your-organization-ID
apis:
  name@version:
    root: path/to/root/definition.yaml

5. If you're using the branchName argument with the Redocly CLI push command, consider adjusting the syntax in any scripts or automated pipelines to avoid warnings in the output.

openapi push openapi.yaml @orgID/name@version --branch devel

openapi push openapi.yaml @orgID/name@version devel

Optionally, you may rename the configuration file from .redocly.yaml to redocly.yaml for your convenience. Keep in mind that only one configuration file is allowed in the working directory or project root.

After making the required changes, save the configuration file. Restart your builds to verify that the basic structure of the file is correct.

If your builds are successful, you can further modify the configuration file to add more APIs, assign labels to them, and control per-API lint and features.openapi settings.

Use the legacy configuration file

To continue using the legacy configuration file, you must preserve the .redocly.yaml file name and the following file structure:

apiDefinitions:
  main: ./openapi/openapi.yaml
  example: ./openapi/example.yaml
lint: []
features.mockServer: []
region: []
resolve: []
referenceDocs: []
registry: []

If you have multiple APIs listed under apiDefinitions, your lint and referenceDocs settings will apply to all those APIs.

To use the Redocly CLI push command with the legacy configuration file, use the following syntax:

openapi push entrypoint @orgID/name@version --branch devel

where entrypoint corresponds to an alias from the apiDefinitions section, or to the path to an API definition file.

To specify a branch, we recommend using the new format --branch branchName or -b branchName instead of using branchName as a standalone argument to avoid warnings in the output.