请求 + 响应示例

Fern 使用 AI 生成的示例自动生成真实的示例，默认启用。使用 x-fern-examples 手动定义特定的示例值。手动示例优先于 AI 生成的示例。您也可以完全禁用 AI 示例。

当您需要关联特定的请求和响应对，或为端点定义多个命名示例时，请使用 x-fern-examples。虽然 OpenAPI 有多个示例字段，但它无法将请求与其对应的响应关联起来。如果您需要您的示例与非 Fern 的 OpenAPI 工具兼容，请使用 fern api enrich 将 x-fern-examples 转换为原生 OpenAPI 示例字段。

x-fern-examples 是一个数组，其中每个元素可以包含关联的 path-parameters、query-parameters、headers、request 和 response 值。可选地，添加 name 字段为每个示例提供描述性标签。

如果您通过 x-fern-global-headers 扩展定义了全局标头，您必须在示例中包含这些标头。

按以下方式构造 request 和 response：

request — 请求体属性直接放在 request 下。
response — 需要嵌套的 body 键来包含响应体属性。

openapi.yml

1 paths:
2   /users/{userId}:
3     get:
4       x-fern-examples:
5         - name: Get user 1234
6           path-parameters:
7             userId: user-1234
8           response:
9             body:
10               name: Foo
11               ssn: 1234
12         - path-parameters:
13             userId: user-4567
14           response:
15             body:
16               name: Foo
17               ssn: 4567
18         - name: Headers example
19           headers:
20             custom_api_key: "capi_12345" # 使用 x-global-header 扩展定义的标头
21             userpool_id: "pool_67890"    # 使用 x-global-header 扩展定义的标头
22   /users:
23     post:
24       x-fern-examples:
25         - name: Create user
26           request:
27             name: Alice
28             email: alice@example.com
29           response:
30             body:
31               id: user-5678
32               name: Alice
33               email: alice@example.com

代码示例

Fern 生成器会自动添加 SDK 代码示例。如果您想为示例指定自定义代码示例，请使用 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")

如果您通过 x-fern-global-headers 扩展定义了全局标头，您必须在示例中包含这些标头。

按以下方式构造 request 和 response：

request — 请求体属性直接放在 request 下。
response — 需要嵌套的 body 键来包含响应体属性。

openapi.yml

1 paths:
2   /users/{userId}:
3     get:
4       x-fern-examples:
5         - name: Get user 1234
6           path-parameters:
7             userId: user-1234
8           response:
9             body:
10               name: Foo
11               ssn: 1234
12         - path-parameters:
13             userId: user-4567
14           response:
15             body:
16               name: Foo
17               ssn: 4567
18         - name: Headers example
19           headers:
20             custom_api_key: "capi_12345" # 使用 x-global-header 扩展定义的标头
21             userpool_id: "pool_67890"    # 使用 x-global-header 扩展定义的标头
22   /users:
23     post:
24       x-fern-examples:
25         - name: Create user
26           request:
27             name: Alice
28             email: alice@example.com
29           response:
30             body:
31               id: user-5678
32               name: Alice
33               email: alice@example.com

代码示例

Fern 生成器会自动添加 SDK 代码示例。如果您想为示例指定自定义代码示例，请使用 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: Get user 1234
6	path-parameters:
7	userId: user-1234
8	response:
9	body:
10	name: Foo
11	ssn: 1234
12	- path-parameters:
13	userId: user-4567
14	response:
15	body:
16	name: Foo
17	ssn: 4567
18	- name: Headers example
19	headers:
20	custom_api_key: "capi_12345" # 使用 x-global-header 扩展定义的标头
21	userpool_id: "pool_67890" # 使用 x-global-header 扩展定义的标头
22	/users:
23	post:
24	x-fern-examples:
25	- name: Create user
26	request:
27	name: Alice
28	email: alice@example.com
29	response:
30	body:
31	id: user-5678
32	name: Alice
33	email: alice@example.com