Request + response examples | Fern Documentation

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. Optionally, you can 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

1 paths:
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
22 components:
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

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

1	paths:
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
22	components:
23	schemas:
24	User:
25	type: object
26	properties:
27	name:
28	type: string
29	ssn:
30	type: integer