请求 + 响应示例（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、request 和 response 值。可选地，添加 name 字段为每个示例提供描述性标签。

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

openapi.yml

1 paths:
2   /users/{userId}:
3     get:
4       x-fern-examples:
5         - name: Headers example # 可选的描述性标签
6           headers:
7             custom_api_key: "capi_12345" # 使用 x-global-header 扩展定义的标头
8             userpool_id: "pool_67890"    # 使用 x-global-header 扩展定义的标头
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

代码示例

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