Last updated

Redocly configuration file

You can configure all of your Redocly tools using a single redocly.yaml configuration file in the root of your project. Your redocly.yaml configurations can be used locally, in CI, or on our hosted platforms to specify the following behaviors:

  • The rules to apply to your APIs and how strictly to lint.
  • The styles and features to use when rendering your API documentation.
  • Project-aware configuration for the VSCode extension.

Redocly CLI searches for the file in the local directory, or you can specify a configuration file with your command.

Our starter projects like openapi-starter include the file for you to edit.

Example Redocly configuration file

An example is worth a thousand words, or so they say. Here's a simple configuration file showing some of the options available and how to use them.

extends:
  - recommended

apis:
  core@v2:
    root: ./openapi/openapi.yaml
    rules:
      no-ambiguous-paths: error
  external@v1:
    root: ./openapi/external.yaml
    labels:
      - external
    theme:
      openapi:
        hideLogo: true

theme:
  openapi:
    schemaExpansionLevel: 2
    generateCodeSamples:
      languages:
        - lang: curl
        - lang: Python

Read on to learn more about the various configuration sections and what you can do with each one.

Using configuration with Redocly CLI

Some of the Redocly CLI commands, such as the lint command, use the API names from the apis object as shortcuts for referencing API descriptions. You can tell the lint command to validate specific API descriptions by using their names from the apis object, like in the following example:

redocly lint core@v2

On the other hand, if you run the command without specifying any aliases, it applies to all API descriptions listed in the apis object of the configuration file.

redocly lint

This runs the lint command for every API defined in the configuration file.

Configuration file overview

Learn about the various sections of the config file, and follow the links for detailed documentation for each.

Expand existing configuration with extends

Use extends to adopt an existing ruleset such as the recommended or minimal standards. You can also define your own rulesets and refer to them here by file path or URL.

While the order of the sections in the configuration file doesn't matter, usually extends is first, and any later rules, preprocessors or decorators defined in this file then override the base settings.

Read the detailed extends documentation to see more information and examples.

Configure linting rules

In the rules section, configure which rules apply, their severity levels, and any options that they support. Configurable rules, and rules from custom plugins are also configured here.

Use this section to adjust the linting rules from the rulesets or other base configuration set in extends, and fine-tune it to meet the needs of your API. Here's an example redocly.yaml, changing some rule severity, and using some additional configuration for a rule.

rules:
  no-unused-components: error
  operation-singular-tag: warn
  boolean-parameter-prefixes:
    severity: error
    prefixes: ['can', 'is', 'has']

You can also define your configurable rules here.

For more information and examples, visit the configuring rules documentation.

Configure OpenAPI features and documentation styles in theme

The theme section includes configuration options for the following aspects of your API documentation:

  • mockServer settings if you use Redocly API registry.
  • styles and features of your API documentation (applies to Redocly API reference and Redoc) in openapi.

mockServer object

You can apply mockServer to individual APIs as well as at the root (default) level. 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 mockServer object is a property of the theme object and allows additional configuration of the mock server behavior. This object is optional.

Fixed properties

errorIfForcedExampleNotFoundboolean

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 description, the mock server returns any other example unless errorIfForcedExampleNotFound is true. Then the mock server returns an error instead.

Default false
strictExamplesboolean

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

Default false

openapi object

The openapi object is a property of the theme object and configures features and theming for API documentation generated from OpenAPI descriptions.

If you need to apply different theming and functionality to individual APIs, add the theme openapi property to the appropriate API in the apis and theme object, and use the same options as the global openapi object.

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

Configure each of the apis independently

For organizations with multiple APIs, versions or environments, having specific configuration for each is a powerful tool. All configuration options can be nested within a specific API entry.

Example of apis configuration

extends:
  - recommended

apis:
  public@v2:
    root: ./openapi/openapi.yaml
    rules:
      operation-4xx-response: off
  internal@v1:
    root: ./internal-openapi/openapi.yaml
    rules:
      security-defined: off
      operation-4xx-response: off
    decorators:
      remove-x-internal: on

Visit the per-API configuration page for detailed documentation and more examples.

Use custom plugins

Use this list to import any custom plugins (omit this section if you have no plugins). Custom plugins are used to add any custom decorators or rules that you want to use, that aren't provided by the Redocly built-in rules, configurable rules, or existing decorators.

Add each plugin by path, relative to the configuration file, to have the plugin contents available to configure. Importing by URL isn't supported, to reduce the risk of malicious code execution.

Find more information on the configuration in plugins page.

Plugin import example

Use the plugins section to import as many plugins as you need to refer to in your config file.

plugins:
  - './local-plugin.js'
  - './another-local-plugin.js'

The rules, decorators, pre-processors and configuration contained in the plugins become available to your configuration file.

Resolve non-public or non-remote URLs

Redocly automatically resolves any API registry link or public URL in your API descriptions. 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

doNotResolveExamplesboolean

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

Default false
httpobject

Description of URL pattern matches and the corresponding headers to use when resolving references.

Example

Here is an example for adding header definitions:

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 is used in the request.

Split up the configuration file

As your config file grows, you may want to split it into multiple parts. Splitting a config file is possible by using references in a config similar to how they are used in OpenAPI descriptions:

extends:
  - recommended

theme:
  openapi:
    $ref: ./openapi-theme.yaml
  mockServer:
    $ref: ./mockserver.yaml

When using the push command with a config file that includes $refs, all referenced files are explicitly uploaded using the --files option.

 
Next page