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

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

 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.

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

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

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

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

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

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

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

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

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