> This page is for API Definitions.

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Overrides

> Customize your API definition using a separate overrides file.

Use an overrides file to customize your OpenAPI, AsyncAPI, or OpenRPC definition without modifying the original spec. This is useful when:

* Your API specification is auto-generated from server code
* You need different configurations for SDKs, documentation, or [generated CLIs](/learn/cli-generator/get-started/customization#overrides-and-overlays)

Overrides are available for OpenAPI, AsyncAPI, and OpenRPC specifications.

> **Warning**
>
> For OpenAPI specs, Fern recommends using [overlays](/learn/api-definitions/openapi/overlays) instead of overrides. Overlays follow the official [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html), support bulk changes with JSONPath wildcards, and are portable across the OpenAPI ecosystem.
>
> Overrides are also fully supported. If overrides are working for your team, there's no need to switch. You can also use both together (overrides are applied first, then overlays).

## Implement overrides

#### Create an overrides file

[Create an `overrides.yml` file](/learn/cli-api-reference/cli-reference/sdk-commands#fern-write-overrides) in the folder that contains your API definition:

```bash {6}
fern/
  ├─ fern.config.json 
  ├─ generators.yml
  └─ spec-folder/
    ├─ spec-file.yml # API definition
    └─ overrides.yml
```

> **Note**
>
> The format of the overrides file is independent from the spec. For example, even if your OpenAPI spec is in JSON format, you can write the overrides in yaml.

#### Customize your spec with Fern extensions

For OpenAPI, AsyncAPI, and OpenRPC, you can use [Fern's extensions](/learn/api-definitions/openapi/extensions/overview) to apply customizations.

**`overrides.yml`**

```yml title="overrides.yml" {4-5}
paths: 
 /users: 
   post: 
    x-fern-sdk-group-name: users
    x-fern-sdk-method-name: create
```

#### Add a reference to generators.yml

**`generators.yml`**

```yaml title="generators.yml"
api:
  specs:
    - openapi: spec-file.yml 
      overrides: ./overrides.yml
```

You can also specify [multiple override files](#managing-overrides-across-apis).

#### Fern combines your spec and overrides

Now when you run `fern generate`, Fern combines your original API specification with the overrides file:

**`openapi.yml`**

```yml openapi.yml
paths: 
 /users: 
   post: 
    description: Create a User
    operationId: users_post
    requestBody: 
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
```

**`overrides.yml`**

```yml title="overrides.yml" {4-5}
paths: 
 /users: 
   post: 
    x-fern-sdk-group-name: users
    x-fern-sdk-method-name: create
```

**`combined`**

```yml title="combined" {4-5}
paths: 
 /users/post: 
  post: 
    x-fern-sdk-group-name: users
    x-fern-sdk-method-name: create      
    description: Create a User
    operationId: users_post
    requestBody: 
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'   
```

## Managing overrides across APIs

The `overrides` field accepts a single path or a list of paths. When multiple paths are provided, overrides are applied sequentially in order, with later files taking precedence over earlier ones for conflicting keys.

#### Shared overrides across multiple specs

When your project has multiple specs that need the same foundational overrides, use a shared base file and layer spec-specific overrides on top. This avoids duplicating common overrides (e.g., SDK method names or authentication extensions) across each spec:

**`generators.yml`**

```yaml title="generators.yml"
api:
  specs:
    - openapi: ./payments-api.yml
      overrides:
        - ./shared-overrides.yml       # Common overrides for all specs
        - ./payments-overrides.yml     # Payments-specific overrides
    - openapi: ./users-api.yml
      overrides:
        - ./shared-overrides.yml       # Same common overrides
        - ./users-overrides.yml        # Users-specific overrides
```

#### Separate overrides for SDKs and docs

When you need entirely different overrides for SDK generation versus documentation, use separate folders with their own `generators.yml`. Each folder references only the overrides relevant to its concern:

**`sdks/generators.yml`**

```yaml title="sdks/generators.yml"
api:
  specs:
    - openapi: ../openapi.yml
      overrides: sdk-overrides.yml
```

If the SDK and docs overrides share a common base, you can use multiple override files within each folder to avoid duplication:

**`sdks/generators.yml`**

```yaml title="sdks/generators.yml"
api:
  specs:
    - openapi: ../openapi.yml
      overrides:
        - ../shared-overrides.yml      # Common overrides for both SDKs and docs
        - sdk-overrides.yml            # SDK-specific overrides
```

#### Overrides for different environments

When your public and internal APIs share the same spec but need different overrides, use multiple override files to layer internal-specific additions on top of the public base. This is especially useful when the internal API is a superset of the public API:

**`generators.yml`**

```yaml title="generators.yml" {5, 12-13}
groups:
  public:
    specs:
      - openapi: openapi.yml
        overrides: public-overrides.yml
    generators:
      ...
  internal:
    specs:
      - openapi: openapi.yml
        overrides:
          - public-overrides.yml           # Base: all public overrides
          - internal-overrides.yml         # Additional: internal-only overrides
    generators:
      ...
```

This avoids duplicating the public overrides in the internal configuration. The `internal-overrides.yml` file only needs to contain the additions specific to the internal API.