Overlay Customizations | Fern Documentation

Overlays allow you to modify your AsyncAPI specification without directly editing the original file. This is useful for:

Adding Fern-specific extensions
Customizing documentation
Adding examples and descriptions
Overriding specific properties

Configure overlays

To use overlays, add them to your generators.yml file:

generators.yml

1 api:
2   specs:
3     - spec: asyncapi.yml
4       overlays:
5         - overlay.yml
6   generators:
7     - name: fernapi/fern-typescript-node-sdk
8       version: 0.8.8

Overlay file structure

Overlay files follow the OpenAPI Overlay Specification format:

overlay.yml

1 overlay: 1.0.0
2 info:
3   title: AsyncAPI Fern Extensions
4   version: 1.0.0
5 actions:
6   - target: $.operations.sendNotification
7     update:
8       x-fern-sdk-method-name: notify
9       summary: Send a notification to a user
10   - target: $.channels['user/events']
11     update:
12       description: Channel for user-related events
13       x-fern-audiences:
14         - public

Add method names

Override SDK method names for better developer experience:

overlay.yml

1 overlay: 1.0.0
2 info:
3   title: SDK Method Names
4   version: 1.0.0
5 actions:
6   - target: $.operations.subscribeToUserEvents
7     update:
8       x-fern-sdk-method-name: onUserEvent
9       summary: Subscribe to user events with callback
10   - target: $.operations.publishOrderUpdate
11     update:
12       x-fern-sdk-method-name: updateOrder
13       summary: Publish order status update

Add examples

Enhance your specification with examples:

overlay.yml

1 overlay: 1.0.0
2 info:
3   title: Message Examples
4   version: 1.0.0
5 actions:
6   - target: $.components.messages.UserSignup
7     update:
8       examples:
9         - name: StandardSignup
10           summary: Regular user signup
11           payload:
12             id: "user_123"
13             email: "john@example.com"
14             name: "John Doe"
15             signupSource: "web"
16             timestamp: "2024-01-15T10:30:00Z"

Filter with audiences

Add audience filtering to operations and channels:

overlay.yml

1 overlay: 1.0.0
2 info:
3   title: Audience Filtering
4   version: 1.0.0
5 actions:
6   - target: $.operations.adminAlert
7     update:
8       x-fern-audiences:
9         - admin
10   - target: $.channels['internal/debug']
11     update:
12       x-fern-audiences:
13         - internal

Add documentation

Enhance descriptions and documentation:

overlay.yml

1 overlay: 1.0.0
2 info:
3   title: Enhanced Documentation
4   version: 1.0.0
5 actions:
6   - target: $.operations.sendMessage
7     update:
8       description: |
9         Send a message to the specified channel. This operation supports
10         real-time delivery with automatic retry on failure. Messages are
11         guaranteed to be delivered at least once.
12       summary: Send message with delivery guarantees

Server configurations

Add server-specific configurations:

overlay.yml

1 overlay: 1.0.0
2 info:
3   title: Server Extensions
4   version: 1.0.0
5 actions:
6   - target: $.servers.production
7     update:
8       x-fern-server-name: Production
9       description: Production environment with high availability
10       bindings:
11         ws:
12           headers:
13             type: object
14             properties:
15               X-API-Version:
16                 type: string
17                 const: "v1"

Multiple overlays

You can apply multiple overlay files in sequence:

generators.yml

1 api:
2   specs:
3     - spec: asyncapi.yml
4       overlays:
5         - base-overlay.yml
6         - sdk-overlay.yml
7         - docs-overlay.yml

Overlays are applied in order, allowing you to build up customizations incrementally while keeping your original AsyncAPI specification clean and focused.