Request + response examples

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 to associate specific request and response pairs or define multiple named examples for an endpoint. OpenAPI has several example fields, but provides no way to link a request with its corresponding response.

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.

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

Examples must include any headers declared with the x-fern-global-headers extension. Place them under headers alongside path-parameters and request.

An endpoint with path parameters:

openapi.yml

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-global-header extension
8             userpool_id: "pool_67890"    # header defined using x-global-header extension
9           path-parameters:
10             userId: user-1234
11           response:
12             body:
13               name: Foo
14               ssn: 1234

An endpoint with a request body:

openapi.yml

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.

openapi.yml

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.

Structure

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

Examples must include any headers declared with the x-fern-global-headers extension. Place them under headers alongside path-parameters and request.

An endpoint with path parameters:

openapi.yml

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-global-header extension
8             userpool_id: "pool_67890"    # header defined using x-global-header extension
9           path-parameters:
10             userId: user-1234
11           response:
12             body:
13               name: Foo
14               ssn: 1234

An endpoint with a request body:

openapi.yml

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.

openapi.yml

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.

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-global-header extension
8	userpool_id: "pool_67890" # header defined using x-global-header extension
9	path-parameters:
10	userId: user-1234
11	response:
12	body:
13	name: Foo
14	ssn: 1234

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