Request + response examples

Fern generates realistic examples automatically using AI-generated examples, enabled by default. Use x-fern-examples to manually define specific values, associate request and response pairs that OpenAPI’s separate example fields can’t link, or define multiple named examples for an endpoint.

Manual examples take priority over AI-generated ones, and you can disable AI examples entirely.

Structure

x-fern-examples is an array. Each element can contain path-parameters, query-parameters, headers, request, and response values that are all associated. Optionally, add a name field to provide a descriptive label.

The request and response values use different shapes:

• request holds the request body properties directly.
• response requires a nested body key containing the response body properties.

An endpoint with path parameters:

1
paths:
2
  /users/{userId}:
3
    get:
4
      x-fern-examples:
5
        - name: Get user 1234 # Optional descriptive label
6
          headers:
7
            custom_api_key: "capi_12345" # header defined using x-fern-global-headers extension
8
            userpool_id: "pool_67890"    # header defined using x-fern-global-headers extension
9
          path-parameters:
10
            userId: user-1234
11
          response:
12
            body:
13
              name: Foo
14
              ssn: 1234

An endpoint with a request body:

1
paths:
2
  /users:
3
    post:
4
      x-fern-examples:
5
        - name: Create user
6
          request:
7
            name: Alice
8
            email: alice@example.com
9
          response:
10
            body:
11
              id: user-5678
12
              name: Alice
13
              email: alice@example.com

Code samples

Fern generators automatically add SDK code samples. To specify custom code samples for an example, use code-samples.

Each code sample uses one of two keys to identify the language:

• sdk — for a language that maps to a Fern-supported SDK tab: curl, python, javascript, typescript, go, ruby, csharp, java, js, node, ts, nodets, golang, dotnet, jvm, c#.
• language — for any other language, or when you want to include an install command.

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")

Convert to native OpenAPI examples

To make x-fern-examples work with non-Fern OpenAPI tools, run fern api enrich to convert them into native OpenAPI example fields.