AsyncAPIExtensions

Overview of AsyncAPI extensions

Fern supports a variety of AsyncAPI extensions that enhance your API specification and generate higher-quality SDKs. You can apply these extensions in two ways: by overlaying them in separate override files or by embedding them directly in your AsyncAPI specification.

Available extensions

The table below shows all available extensions and links to detailed documentation for each one.

ExtensionDescription
x-fern-ignoreSkip reading specific operations, channels, or schemas
x-fern-examplesProvide additional examples for better SDK documentation
x-fern-paginationConfigure pagination for operations that return multiple results
x-fern-retryConfigure retry behavior for operations
x-fern-streamingMark operations as streaming for appropriate SDK generation
x-fern-error-handlingConfigure error handling for operations
x-fern-server-nameSpecify custom names for servers
x-fern-availabilityMark features as available in specific SDK versions
Request a new extension

If there’s an extension you want that doesn’t already exist, file an issue to start a discussion about it.

Overlaying extensions

Overlaying extensions allows you to keep your original API specification clean while adding Fern-specific customizations in a separate file. This approach is ideal when you’re using multiple tools that consume your API spec, or when you want to maintain a pristine source specification.

To use overlays, specify an overrides file in your generators.yml configuration.

The example below shows how to overlay SDK naming extensions. The first tab shows the generators.yml configuration that references an overrides file, the second tab contains the overrides file with Fern extensions, and the third tab shows the final result when the extensions are applied to your original API specification.

1api:
2  path: ./spec-folder/spec-file.yaml
3  overrides: ./spec-folder/overrides.yaml # Reference your overrides file
4default-group: sdk
5groups:
6  sdk:
7    generators:
8      - name: fernapi/fern-python-sdk
9        version: 2.2.0

Embedding extensions

Instead of using overlay files, you can embed Fern extensions directly within your API specification or source code. This approach is useful when you want to keep extensions close to your API definitions or when using frameworks that support custom extensions.

Direct embedding

You can add Fern extensions directly to your API specification:

spec-file.yml
1paths:
2  /users:
3    get:
4      x-fern-sdk-group-name: users
5      x-fern-sdk-method-name: listUsers
6      x-fern-availability: generally-available
7      summary: Get a list of users
8      responses:
9        '200':
10          description: Successful response