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 are 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 and are portable across different tools.

However, overrides are also fully supported. If your team already uses overrides, there’s no need to switch unless you need advanced functionality. 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

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

Use different overrides files for SDK generation versus documentation by creating separate folders with their own generators.yml:

$ 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

Overrides for different environments

Configure different overrides for production versus internal APIs:

generators.yml

1 groups:
2   production:
3     specs:
4       - openapi: openapi.yml
5         overrides: production-overrides.yml
6     generators:
7       ...
8   internal:
9     specs:
10       - openapi: openapi.yml
11         overrides: internal-overrides.yml
12     generators:
13       ...