Fern home pagelight logo
Using OpenAPI
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 together
  • x-fern-sdk-method-name which is used as the method name in the SDK

The OpenAPI below will client.users.create():

openapi.yaml
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():

openapi.yaml
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.

openapi.yml
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

openapi.yml
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

operand.ts
export enum Operand {
  GreaterThan = ">",
  LessThan = "<",
}

​
Schema names

OpenAPI allows you to define inlined schemas that do not have names.

openapi.yml
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.

openapi.yml
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;
}