请求 + 响应示例（OpenAPI）

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。

每个代码示例使用以下两个键之一来标识语言：

键	值	使用场景
`sdk`	支持的 SDK 语言之一：`curl`、`python`、`javascript`、`typescript`、`go`、`ruby`、`csharp`、`java`、`js`、`node`、`ts`、`nodets`、`golang`、`dotnet`、`jvm`、`c#`	代码示例对应 Fern 支持的 SDK 语言标签
`language`	任意字符串	代码示例的语言不在支持列表中，或您需要包含 `install` 命令

使用 sdk：

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

使用 language：

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             - language: php
13               install: composer require acme/sdk
14               code: |
15                 use Acme\Client;
16 
17                 $client = new Client();
18                 $client->users->get("user-1234");