> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJiZDNhZTk0Zi1lODJkLTQ2NjQtOTkxZi05NjI5OGI4OWFjMmYiLCJleHAiOjE3Nzg0OTE0MTcsImlhdCI6MTc3ODQ5MTExN30.PPa_jwDQE4CtKYDVTYKXJyTPnhSZBiCns0wzR9lhFt8
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 请求 + 响应示例

> 使用 x-fern-examples 配置 OpenAPI 请求和响应示例。在您的 API 定义中关联路径参数、查询参数和响应。

<Note>
  Fern 使用 [AI 生成的示例](/learn/docs/ai-features/ai-examples) 自动生成真实的示例，默认启用。使用 `x-fern-examples` 手动定义特定的示例值。手动示例优先于 AI 生成的示例。您也可以[完全禁用 AI 示例](/learn/docs/configuration/site-level-settings#ai-examplesenabled)。
</Note>

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

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

如果您[通过 `x-fern-global-headers` 扩展定义了全局标头](/api-definitions/openapi/extensions/global-headers)，您必须在示例中包含这些标头。

```yaml title="openapi.yml" {4-21}
paths:
  /users/{userId}:
    get:
      x-fern-examples:
        - name: Headers example # 可选的描述性标签
          headers:
            custom_api_key: "capi_12345" # 使用 x-global-header 扩展定义的标头
            userpool_id: "pool_67890"    # 使用 x-global-header 扩展定义的标头
        - name: Get user 1234
          path-parameters:
            userId: user-1234
          response:
            body:
              name: Foo
              ssn: 1234
        - path-parameters:
            userId: user-4567
          response:
            body:
              name: Foo
              ssn: 4567
components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
        ssn:
          type: integer
```

### 代码示例

Fern 生成器会自动添加 SDK 代码示例。如果您想为示例指定自定义代码示例，请使用 `code-samples`。

```yaml title="openapi.yml" {11-16}
paths:
  /users/{userId}:
    get:
      x-fern-examples:
        - path-parameters:
            userId: user-1234
          response:
            body:
              name: Foo
              ssn: 1234
          code-samples:
            - sdk: typescript
              code: |
                import { UserClient } from "...";

                client.users.get("user-1234")
```