OpenRPCExtensions

Overview of OpenRPC extensions

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

Available extensions

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

ExtensionDescription
x-fern-ignoreSkip reading specific methods or schemas
x-fern-examplesProvide additional examples for better SDK documentation
x-fern-paginationConfigure pagination for methods that return multiple results
x-fern-retryConfigure retry behavior for methods
x-fern-timeoutConfigure timeout settings for methods
x-fern-error-handlingConfigure error handling for methods
x-fern-availabilityMark features as available in specific SDK versions
x-fern-streamingMark methods as streaming for appropriate SDK generation
x-fern-server-nameSpecify custom names for servers
x-fern-base-pathConfigure base paths for generated SDK clients
x-fern-sdk-group-nameGroup related methods in the SDK
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