OpenAPI extensions for SDKs
Fern supports different OpenAPI extensions so that you can generate higher-quality SDKs.
SDK method names
By default, Fern uses the tag
and operationId
fields to generate the SDK method. So an endpoint with a
tag users
and operationId users_create
will generate an SDK that reads client.users.create()
.
To explicitly set the SDK method you can leverage the extensions:
x-fern-sdk-group-name
which groups SDK methods togetherx-fern-sdk-method-name
which is used as the method name in the SDK
The OpenAPI below will generate client.users.create()
:
If you omit the x-fern-sdk-group-name
extension, then the generated SDK method will live at the root.
For example, the following OpenAPI will generate client.create_user()
:
If you add more than one x-fern-sdk-group-name
extension, then the generated SDK will nested group names. The order of the group names is preserved in the generated SDK method.
For example, the following OpenAPI will generate client.admin.users.create()
:
API version
You can define your API version scheme, such as a X-API-Version
header. The supported versions and default value are specified like so:
Authentication overrides
For authentication within your SDK, you may want to customize the:
- Names of the parameters a user will populate to provide their credentials
- Any environment variable the SDK can scan for to automatically provide the user’s credentials automatically
By default, Fern uses names for authentication parameters like api_key, username and password, etc.
Note that this configuration is optional, and even when provided name
or env
may be provided alone, both are not required.
For bearer authentication:
In a Python SDK for example, the above configuration would produce a client that looks like:
Similarly, for basic authentication the configuration is:
And for a custom auth header configuration:
This adds a header of the form X-API-Key: Token <value>
to the request.
Global headers
At times, your API will leverage certain headers for every endpoint, or the majority of them, we call these “global headers”. For convenience, generated Fern SDKs expose “global headers” to easily be updated on API calls. Take for example an API key, if we declare the API key as a global header, a user will be able to plug theirs in easily:
To configure global headers, Fern will automatically pull out headers that are used in every request, or the majority of requests, and mark them as global.
In order to label additional headers as global, or to alias the names of global headers, you can leverage the x-fern-global-headers
extension:
yields the following client:
Enum descriptions and names
OpenAPI doesn’t natively support adding descriptions to enum values. To do this in Fern you can use the x-fern-enum
extension.
In the example below, we’ve added some descriptions to enum values. These descriptions will propagate into the generated SDK and docs website.
x-fern-enum
also supports a name
field that allows you to customize the name of the enum in code.
This is particularly useful when you have enums that rely on symbolic characters that would otherwise cause
generated code not to compile.
For example, the following OpenAPI
would generate
Schema names
OpenAPI allows you to define inlined schemas that do not have names.
Fern automatically generates names for all the inlined schemas. For example, in this example,
Fern would generate the name CastItem
for the inlined array item schema.
If you want to override the generated name, you can use the extension x-fern-type-name
.
This would replace CastItem
with Person
and the generated code would read more idiomatically:
Parameter names
The x-fern-parameter-name
extension allows you to customize the variable name of OpenAPI
parameters.
For example, if you have a header X-API-Version
, you may want the parameter
in code to be called version
.
Property Names
The x-fern-property-name
extension allows you to customize the variable name for object
properties.
For example, if you had a property called _metadata
in your schema but you wanted the
variable to be called data
in your SDK you would do the following:
Server names
The x-fern-server-name
extension is used to name your servers.
In a generated TypeScript SDK, you’d see:
Base path
The x-fern-base-path
extension is used to configure the base path prepended to every endpoint.
In the example below, we have configured the /v1
base path so the full endpoint path is
https://api.example.com/v1/users
.
Audiences
Audiences are a useful tool for segmenting your API for different consumers. You can configure your Fern Docs to publish documentation specific to an Audience
. You can use audiences in your Fern Definition, too.
Common examples of audiences include:
- Internal consumers (e.g., frontend developers who use the API)
- Beta testers
- Customers
By default, if no audience is specified, it will be accessible to all consumers.
Audiences for Endpoints
To mark an endpoint with a particular audience, add the x-fern-audiences
extension to the relevant endpoint.
In the example below, the POST /users/sendEmail
endpoint is only available to internal consumers:
Audiences for Components
Components can be marked for different audiences, as well.
In this example, the Email
type is available to both internal and beta customers, while the to
property is available to beta customers only:
Audiences for SDKs
In generators.yml
, you can apply audience filters so that only certain
endpoints are passed to the generators.
The following example configures the SDKs to filter for the customers
audience:
Audiences for Docs
If generating Fern Docs, update your docs.yml
configuration to include your audiences.
The following example shows how to configure your docs.yml
to publish documentation for the customers
audience:
Streaming
The x-fern-streaming
extension is used to specify that an endpoint’s response is streamed.
Include the x-fern-streaming
extension within your endpoint like so:
If you want to generate both a non-streaming and streaming SDK method variant for the same endpoint,
you can use the extended x-fern-streaming
syntax:
The same endpoint path (/logs
in the example above) is used for both of the generated SDK methods,
and the stream-condition
setting includes a property in the request body that is used to
distinguish whether the response should be streamed.
In the example above, a property named stream
is sent as true
for the streaming variant,
and sent as false
for the non-streaming variant. Additionally, a stream of the Log
type
is returned in the streaming variant, whereas the Logs
array is returned in the non-streaming
variant.
Ignoring schemas or endpoints
If you want Fern to skip reading any endpoints or schemas, use the x-fern-ignore
extension.
To skip an endpoint, add x-fern-ignore: true
at the operation level.
To skip a schema, add x-fern-ignore: true
at the schema level.
Overlaying extensions
Because of the number of tools that use OpenAPI, it may be more convenient to
“overlay” your fern specific OpenAPI extensions onto your original definition.
In order to do this you can specify your overrides file in generators.yml
.
Below is an example of how someone can overlay the extensions x-fern-sdk-method-name
and
x-fern-sdk-group-name
without polluting their original OpenAPI. The combined result is
shown in the third tab.
Embedding extensions
If instead of overlaying your extensions within an overrides file, as mentioned above. Certain frameworks that generate OpenAPI specs make it easy to embed extensions directly from code.
FastAPI
Please view our page on FastAPI for more information on how to extend your OpenAPI spec within FastAPI.
Request + response examples
While OpenAPI has several fields for examples, there is no easy way to associate a request with a response. This is especially useful when you want to show more than one example in your documentation.
x-fern-examples
is an array of examples. Each element of the array
can contain path-parameters
, query-parameters
, request
and response
examples values that are all associated.
Code samples
If you’d like to specify custom code samples for your example, use code-samples
.
If you’re on the Fern Starter plan or higher for SDKs you won’t have to worry about manually adding code samples! Our generators do that for you.
Availability
The x-fern-availability
extension is used to mark the availability of an endpoint. The availability information propagates into the generated Fern Docs website as visual tags.
The options are:
beta
generally-available
deprecated
The example below marks that the POST /pet
endpoint is deprecated
.
This renders as:
![Screenshot of API Reference endpoint with tag showing deprecated](https://fern-image-hosting.s3.amazonaws.com/fern/x-fern-availability-example.png)
Request new extensions
If there’s an extension you want that doesn’t already exist, file an issue to start a discussion about it.