Overrides | Fern Documentation

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 versus documentation

Overrides are available for OpenAPI, AsyncAPI, and OpenRPC specifications. They’re not needed for Fern Definition since you can directly edit those files.

For OpenAPI specs, Fern recommends using overlays instead of overrides. Overlays follow the official OpenAPI Overlay Specification, 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 in the folder that contains your API definition:

$ 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 to apply customizations.

overrides.yml

1 paths: 
2  /users: 
3    post: 
4     x-fern-sdk-group-name: users
5     x-fern-sdk-method-name: create

Add a reference to generators.yml

generators.yml

1 api:
2   specs:
3     - openapi: spec-file.yml 
4       overrides: ./overrides.yml

You can also specify multiple override files.

Fern combines your spec and overrides

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

1 paths: 
2  /users: 
3    post: 
4     description: Create a User
5     operationId: users_post
6     requestBody: 
7       content:
8         application/json:
9           schema:
10             $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

1 api:
2   specs:
3     - openapi: ./payments-api.yml
4       overrides:
5         - ./shared-overrides.yml       # Common overrides for all specs
6         - ./payments-overrides.yml     # Payments-specific overrides
7     - openapi: ./users-api.yml
8       overrides:
9         - ./shared-overrides.yml       # Same common overrides
10         - ./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:

fern

fern.config.json

openapi.yml

docs

generators.yml

docs-overrides.yml

sdks

generators.yml

sdk-overrides.yml

sdks/generators.yml

1 api:
2   specs:
3     - openapi: ../openapi.yml
4       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

1 api:
2   specs:
3     - openapi: ../openapi.yml
4       overrides:
5         - ../shared-overrides.yml      # Common overrides for both SDKs and docs
6         - 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

1 groups:
2   public:
3     specs:
4       - openapi: openapi.yml
5         overrides: public-overrides.yml
6     generators:
7       ...
8   internal:
9     specs:
10       - openapi: openapi.yml
11         overrides:
12           - public-overrides.yml           # Base: all public overrides
13           - internal-overrides.yml         # Additional: internal-only overrides
14     generators:
15       ...

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.