OpenAPIExtensions

Request + response examples

View as Markdown

Fern generates realistic examples automatically using AI-generated examples, enabled by default. Use x-fern-examples to manually define specific example values. Manual examples take priority over AI-generated ones. You can also disable AI examples entirely.

Use x-fern-examples when you need to associate specific request and response pairs or define multiple named examples for an endpoint. While OpenAPI has several example fields, it provides no way to link a request with its corresponding response.

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

If you defined global headers via the x-fern-global-headers extension, you must include the headers in your examples.

openapi.yml
1paths:
2  /users/{userId}:
3    get:
4      x-fern-examples:
5        - name: Headers example # Optional descriptive label
6          headers:
7            custom_api_key: "capi_12345" # header defined using x-global-header extension
8            userpool_id: "pool_67890"    # header defined using x-global-header extension
9        - name: Get user 1234
10          path-parameters:
11            userId: user-1234
12          response:
13            body:
14              name: Foo
15              ssn: 1234
16        - path-parameters:
17            userId: user-4567
18          response:
19            body:
20              name: Foo
21              ssn: 4567
22components:
23  schemas:
24    User:
25      type: object
26      properties:
27        name:
28          type: string
29        ssn:
30          type: integer

Code samples

Fern generators automatically add SDK code samples. If you’d like to specify custom code samples for your example, use code-samples.

openapi.yml
1paths:
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")