Overrides | Fern Documentation

Use an overrides file to customize your OpenAPI, AsyncAPI, OpenRPC, or gRPC 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, OpenRPC, and gRPC specifications. They are not needed for Fern Definition since you can directly edit those files.

While you can also embed Fern extensions directly in your API specification, using overrides files is the recommended approach as it keeps your original spec clean and separates concerns.

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, and gRPC, 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

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'

Separate overrides for SDKs and Docs

For separate SDK and documentation configurations, you can use different override files in separate folders with their own generators.yml files.

$ fern/
>   ├─ fern.config.json
>   ├─ generators.yml 
>   └─ apis/
>     ├─ docs/ # Documentation configuration
>     │   ├─ generators.yml 
>     │   └─ docs-overrides.yml # Documentation-specific overrides
>     ├─ sdks/ # SDK configuration
>     │   ├─ generators.yml 
>     │   └─ sdk-overrides.yml # SDK-specific overrides
>     └─ openapi/
>         └─ openapi.yml # Original API specification

Both generators.yml files can be identical except for pointing to different override files:

Docs

SDKs

docs/generators.yml

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

Overrides for different environments

You can configure different override files for different environments. Overrides are applied in order, allowing you to build up customizations incrementally while keeping your original specification clean and focused.

generators.yml

1 groups:
2   production:
3     audiences: [public]
4     specs:
5       - openrpc: openrpc.yml
6         overrides:
7           - production-override.yml
8     generators:
9       - name: fernapi/fern-typescript-node-sdk
10         version: 0.8.8
11   internal:
12     audiences: [admin, internal]
13     specs:
14       - openrpc: openrpc.yml
15         override:
16           - internal-override.yml
17     generators:
18       - name: fernapi/fern-typescript-node-sdk
19         version: 0.8.8

Definition-specific extensions

Learn more about the Fern extensions you can use to customize your definition: