Overview of OpenAPI extensions | Fern Documentation

Fern supports a variety of OpenAPI 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 OpenAPI specification.

Available extensions

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

Extension	Description
`x-fern-version`	Configure API version schemes and headers
`x-fern-audiences`	Filter endpoints, schemas, and properties by audience
`x-fern-availability`	Mark availability status (beta, generally-available, deprecated)
`x-fern-base-path`	Set base path prepended to all endpoints
`x-fern-enum`	Add descriptions and custom names to enum values
`x-fern-examples`	Associate request and response examples
`x-fern-global-headers`	Configure headers used across all endpoints
`x-fern-ignore`	Skip reading specific endpoints or schemas
`x-fern-sdk-method-name`	Customize SDK method names
`x-fern-sdk-group-name`	Organize methods into SDK groups
`x-fern-parameter-name`	Customize parameter variable names
`x-fern-property-name`	Customize object property variable names
`x-fern-type-name`	Override auto-generated names for inline schemas
`x-fern-server-name`	Name your servers

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.

1 api:
2   path: ./spec-folder/spec-file.yaml
3   overrides: ./spec-folder/overrides.yaml # Reference your overrides file
4 default-group: sdk
5 groups:
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

1 paths:
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

FastAPI

FastAPI allows you to add extensions directly in your route decorators and models. See our FastAPI integration guide for detailed examples.