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
toapis
. -
Previously, every API under
apiDefinitions
was identified by itsdefinitionId
or alias. Now, the APIs underapis
are identified by their name and version in the formatname@version
. The version is optional, and when not provided, Redocly apps interpret it aslatest
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 separateroot
property to provide the path to the OpenAPI definition. -
Renamed
referenceDocs
tofeatures.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 theorganization
property in the configuration file. Thepush
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.
-
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
.
-
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.
-
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.
-
Rename
apiDefinitions
toapis
. -
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
-
Rename
referenceDocs
tofeatures.openapi
. -
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
-
If you're using the
branchName
argument with the Redocly CLIpush
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.