跳到导航
OpenAPI扩展

请求 + 响应示例

以 Markdown 格式查看

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
paths:
  /users/{userId}:
    get:
      x-fern-examples:
        - 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
        - name: Headers example
          headers:
            custom_api_key: "capi_12345" # 使用 x-global-header 扩展定义的标头
            userpool_id: "pool_67890"    # 使用 x-global-header 扩展定义的标头
  /users:
    post:
      x-fern-examples:
        - name: Create user
          request:
            name: Alice
            email: alice@example.com
          response:
            body:
              id: user-5678
              name: Alice
              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
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")

使用 language：

openapi.yml
paths:
  /users/{userId}:
    get:
      x-fern-examples:
        - path-parameters:
            userId: user-1234
          response:
            body:
              name: Foo
              ssn: 1234
          code-samples:
            - language: php
              install: composer require acme/sdk
              code: |
                use Acme\Client;
                $client = new Client();
                $client->users->get("user-1234");