Using extensions
Fern supports different OpenAPI extensions so that you can generate higher-quality SDKs. If there’s an extension you want that doesn’t already exist, file an issue.
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 client.users.create()
:
paths:
/users
post:
x-fern-sdk-group-name: users
x-fern-sdk-method-name: 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()
:
paths:
/users:
post:
x-fern-sdk-method-name: create_user
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.
components:
schemas:
CardSuit:
enum:
- clubs
- diamonds
- hearts
- spades
x-fern-enum: # <------
clubs:
description: Some docs about clubs
spades:
description: Some docs about spades
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
components:
schemas:
Operand:
enum:
- >
- <
x-fern-enum:
>:
name: GreaterThan
description: Checks if value is greater than
<:
name: LessThan
description: Checks if value is less than
would generate
export enum Operand {
GreaterThan = ">",
LessThan = "<",
}
Schema names
OpenAPI allows you to define inlined schemas that do not have names.
components:
schemas:
Movie:
type: object
properties:
name:
type: string
cast:
type: array
items:
type: object # <---------- Inline Type
properties:
firstName:
type: string
lastName:
type: string
age:
type: integer
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.
export interface Movie {
name?: string;
cast?: CastItem[]
}
export interface CastItem { # <----- Auto-generated name
firstName?: string;
lastName?: string;
age?: integer;
}
If you want to override the generated name, you can use the extension x-fern-type-name
.
components:
schemas:
Movie:
type: object
properties:
name:
type: string
cast:
type: array
items:
type: object
x-fern-type-name: Person # <----------
properties:
firstName:
type: string
lastName:
type: string
age:
type: integer
This would replace CastItem
with Person
and the generated code would read more idiomatically:
export interface Movie {
name?: string;
cast?: Person[]
}
export interface Person { # <----- Overridden name
firstName?: string;
lastName?: string;
age?: integer;
}