redocly-cli/docs/configuration/configuration-file.mdx

import { JsonSchema } from '@redocly/developer-portal/ui';
import Schema from './schema.yaml';
import { StyledContent } from '../../components/styled.elements';


# Redocly configuration file

The Redocly configuration file controls options for the OpenAPI CLI tool.
It is also used across other Redocly products to help you control their behavior.

- 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 when building 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.

## Filename and location

The Redocly configuration file must be named `redocly.yaml` or `.redocly.yaml`, and placed into your working directory or the root of your project (depending on the Redocly product you're using).

OpenAPI CLI will search for the configuration file in the working directory.

:::warning

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.

:::

## File format and structure

The Redocly configuration file must be in YAML format.

<StyledContent>
  <JsonSchema
    schema={Schema}
    options={{
      schemaExpansionLevel:3,
    }}
  />
</StyledContent>

### Example
```yaml
organization: testing_redocly
apis:
  core@v2:
    root: ./openapi/openapi.yaml
    lint:
      rules:
        example-rule: warn
  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
```

### organization

The `organization` property requires the organization ID of your Redocly Workflows organization.
When specified in the configuration file, it can be used by the `openapi push` command.
The `push` command uses the following order of precedence: first, it takes the organization ID from command-line arguments (if provided).
If the organization ID is not provided explicitly, it takes it from the configuration file.

Note that the organization ID is not the same as the organization name in Workflows.

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


### apis

The `apis` section is used to configure one or more APIs. Every API in the section 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 section must be unique.

For every API listed in the section, you must provide the path to the OpenAPI definition using the `root` property.

```yaml
apis:
  name@version:
    root: ./openapi/openapi.yaml
    labels:
      - production
    lint: []
    features.openapi: []
lint:
  rules:
    example-rule-name: error
features.openapi:
  pagination: section
  showConsole: true
  theme:
    menu:
      backgroundColor: '#fffff'
```


The `apis` section supports several optional properties for every listed API.

**labels**

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**

In addition to the global (top-level) `lint` section, you can add one to each API listed in `apis`. This allows you to use different rules and decorators for different APIs.

**features.openapi**

In addition to the global (top-level) `features.openapi` section, you can add one to each API listed in `apis`. This allows you to use different API reference docs settings for different APIs.
This section supports identical format and options as the global `features.openapi` section.


:::warning Important

Not all `lint` options are supported in per-API configuration.
Consult the table below to understand how each configuration section applies to your APIs.

:::


Configuration section | Per-API support | Behavior
-- | -- | --
lint.extends | ❗ | API settings override global settings.
lint.rules | ✅ | API and global settings merge. In case of conflict, API takes priority.
lint.decorators | ✅ | API and global settings merge. In case of conflict, API takes priority.
lint.preprocessors | ✅ | API and global settings merge. In case of conflict, API takes priority.
lint.plugins | ❌ | Available in global configuration only.
features.openapi | ✅ | API and global settings merge. In case of conflict, API takes priority.
features.mockServer | ✅ | API and global settings merge. In case of conflict, API takes priority.


Some of the OpenAPI CLI commands, such as the [lint command](../commands/lint.md), use the API names from the `apis` section as shortcuts for referencing API definitions.
You can tell the `lint` command to validate specific API definitions by using their names from the `apis` section, like in the following example:

```shell
openapi lint core
```

On the other hand, if you run the command without specifying any aliases, it will apply to all API definitions listed in the `apis` section:

```shell
openapi 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](../guides/lint.md).


### features.mockServer

The API registry supports [the mock server feature](../../api-registry/guides/mock-server-quickstart.md) 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` section allows additional configuration of the mock server behavior.
This section is optional.

The `features.mockServer` section supports fields listed in the following table.

| Property | Description | Default |
| --- | --- | --- |
| errorIfForcedExampleNotFound | Users can force specific examples in the response by adding the optional `x-redocly-response-body-example` header to their requests. By default, if an example ID provided in the request is not found in the API definition, the mock server returns any other example. If you set `errorIfForcedExampleNotFound: true`, the mock server will return an error instead. | false |
| strictExamples | By default, the mock server automatically enhances responses with heuristics like substituting the response fields with request parameter values. To prevent this behavior, set `strictExamples: true`. When this is set, examples are returned in the response unmodified, exactly how they are defined in the OpenAPI document. | false |


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

Region | Domain
-----|:---------
`us` | api.redoc.ly
`eu` | api.eu.redocly.com

The `eu` region is limited to enterprise customers.

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

- the `REDOCLY_DOMAIN` environment variable

```sh
export REDOCLY_DOMAIN={domain}
```

- the `--region` option with `login` and `push` commands

```sh
openapi login --region=eu
```

- the `region` top-level property in the Redocly configuration file

```yaml
apis:
  core@v1:
    root: ./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:

```yaml
resolve:
  http:
    headers:
      - # header configuration
```

The `headers` section supports fields listed in the following table.

| Property | Description | Examples |
| --- | --- | --- |
| matches | Glob match against the URL. | `https://api.example.com/**` or `https://api.example.com/*.json`|
| name | HTTP header name. | `Authorization` or `X-API-KEY`|
| value | The value of the header. Mutually exclusive with `envVariable`. | `123-abc`|
| envVariable | The 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:

```yaml
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 precedence when a URL matches multiple patterns. Therefore, only the header from the first match will be used in the request.


### features.openapi

The `features.openapi` section configures features (availability and options) and theming (style, fonts, colors) for API reference documentation generated from API definitions.

There are two products: Redoc Community Edition (CE) and Redocly Reference. Reference 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](../../api-reference-docs/configuration/index.mdx).