Other extensions

Fern supports different OpenAPI extensions so that you can generate higher-quality SDKs.

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:

1
x-fern-version:
2
  version:
3
    header: X-API-Version
4
    default: "2.0.0"
5
    values:
6
      - "1.0.0"
7
      - "2.0.0"
8
      - "latest"
9
paths: ...

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:

1
import os
2
3
class Client:
4
5
  def __init__(self, *, apiKey: str):

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:

1
x-fern-global-headers:
2
  - header: custom_api_key
3
    name: api_key
4
  - header: userpool_id
5
    optional: true

yields the following client:

1
import os
2
3
class Client:
4
5
  def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str])

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.

1
components:
2
  schemas:
3
    CardSuit:
4
      enum:
5
        - clubs
6
        - diamonds
7
        - hearts
8
        - spades
9
      x-fern-enum:
10
        clubs:
11
          description: Some docs about clubs
12
        spades:
13
          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

1
components:
2
  schemas:
3
    Operand:
4
      enum:
5
        - '>'
6
        - '<'
7
      x-fern-enum:
8
        '>':
9
          name: GreaterThan
10
          description: Checks if value is greater than
11
        '<':
12
          name: LessThan
13
          description: Checks if value is less than

would generate

1
export enum Operand {
2
  GreaterThan = ">",
3
  LessThan = "<"
4
}

Schema names

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

1
components:
2
  schemas:
3
    Movie:
4
      type: object
5
      properties:
6
        name:
7
          type: string
8
        cast:
9
          type: array
10
          items:
11
            type: object
12
            properties:
13
              firstName:
14
                type: string
15
              lastName:
16
                type: string
17
              age:
18
                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.

1
export interface Movie {
2
  name?: string;
3
  cast?: CastItem[];
4
}
5
6
export interface CastItem {
7
  firstName?: string;
8
  lastName?: string;
9
  age?: integer;
10
}

If you want to override the generated name, you can use the extension x-fern-type-name.

1
components:
2
  schemas:
3
    Movie:
4
      type: object
5
      properties:
6
        name:
7
          type: string
8
        cast:
9
          type: array
10
          items:
11
            type: object
12
            x-fern-type-name: Person
13
            properties:
14
              firstName:
15
                type: string
16
              lastName:
17
                type: string
18
              age:
19
                type: integer

This would replace CastItem with Person and the generated code would read more idiomatically:

1
export interface Movie {
2
  name?: string;
3
  cast?: Person[];
4
}
5
6
export interface Person {
7
  firstName?: string;
8
  lastName?: string;
9
  age?: integer;
10
}

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:

1
components:
2
  schemas:
3
    MyUser:
4
      _metadata:
5
        type: object
6
        x-fern-property-name: data

Server names

The x-fern-server-name extension is used to name your servers.

1
servers:
2
  - url: https://api.example.com
3
    x-fern-server-name: Production
4
  - url: https://sandbox.example.com
5
    x-fern-server-name: Sandbox

In a generated TypeScript SDK, you’d see:

1
export const ExampleEnvironment = {
2
  Production: "https://api.example.com"
3
} as const;
4
5
export type ExampleEnvironment = typeof ExampleEnvironment.Production;

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.

1
x-fern-base-path: /v1
2
servers:
3
  - url: https://api.example.com
4
paths:
5
  /users: ...

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.

1
paths:
2
  /users:
3
    get:
4
      x-fern-ignore: true
5
      ...

To skip a schema, add x-fern-ignore: true at the schema level.

1
components:
2
  schemas:
3
    SchemaToSkip:
4
      x-fern-ignore: true
5
      ...

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.

1
api:
2
  path: ./openapi/openapi.yaml
3
  overrides: ./openapi/overrides.yaml
4
default-group: sdk
5
groups:
6
  sdk:
7
    generators:
8
      - name: fernapi/fern-python-sdk
9
        version: 2.2.0

Embedding extensions

If instead of overlaying your extensions within an overrides file, as mentioned above. Certain frameworks that generate OpenAPI Specifications 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 Specification 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.

1
paths:
2
  /users/{userId}:
3
    get:
4
      x-fern-examples:
5
        - path-parameters:
6
            userId: user-1234
7
          response:
8
            body:
9
              name: Foo
10
              ssn: 1234
11
        - path-parameters:
12
            userId: user-4567
13
          response:
14
            body:
15
              name: Foo
16
              ssn: 4567
17
components:
18
  schemas:
19
    User:
20
      type: object
21
      properties:
22
        name:
23
          type: string
24
        ssn:
25
          type: integer

Code samples

If you’d like to specify custom code samples for your example, use code-samples.

1
paths:
2
  /users/{userId}:
3
    get:
4
      x-fern-examples:
5
        - path-parameters:
6
            userId: user-1234
7
          response:
8
            body:
9
              name: Foo
10
              ssn: 1234
11
          code-samples:
12
            - sdk: typescript
13
              code: |
14
                import { UserClient } from "...";
15
16
                client.users.get("user-1234")

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.

1
paths:
2
  /pet:
3
    post:
4
      x-fern-availability: deprecated

This renders as:

Request new extensions

If there’s an extension you want that doesn’t already exist, file an issue to start a discussion about it.