# 添加 SDK 示例 (/zh/api-playground/adding-sdk-examples)

<!-- agent-signals: reading_time_min: 1 · est_tokens: 950 · updated: 2026-09-23 -->
Related: [SDK 参考设置](/zh/api-playground/sdk-reference-setup.md), [复杂数据类型](/zh/api-playground/complex-data-types.md), [多种响应](/zh/api-playground/multiple-responses.md), [管理页面可见性](/zh/api-playground/managing-page-visibility.md), [手动创建 API 文档页面](/zh/api-playground/mdx-setup.md)

如果你的用户通过 SDK 而非直接的网络请求与 API 交互，请使用 `x-codeSamples` 扩展添加 SDK 代码示例。Mintlify 会在你的 OpenAPI 页面上显示这些示例。

你可以自行编写这些示例。如果你使用 Speakeasy 生成 SDK，Speakeasy 可以自动将示例添加到你的规范中。

<div id="add-examples-manually">
  ## 手动添加示例 [#手动添加示例]
</div>

将 `x-codeSamples` 属性添加到任意请求方法。它具有以下 schema。

<ParamField body="lang" type="string">
  代码示例的语言。
</ParamField>

<ParamField body="label" type="string">
  示例的标签。当为同一个端点提供多个示例时非常有用。
</ParamField>

<ParamField body="source" type="string">
  示例的源代码。
</ParamField>

以下示例展示了一个植物管理应用的代码示例，该应用同时提供 Bash CLI 工具和 JavaScript SDK。

```yaml
paths:
  /plants:
    get:
      # ...
      x-codeSamples:
        - lang: bash
          label: List all unwatered plants
          source: |
            planter list -u
        - lang: javascript
          label: List all unwatered plants
          source: |
            const planter = require('planter');
            planter.list({ unwatered: true });
        - lang: bash
          label: List all potted plants
          source: |
            planter list -p
        - lang: javascript
          label: List all potted plants
          source: |
            const planter = require('planter');
            planter.list({ potted: true });
```

<div id="generate-examples-with-speakeasy">
  ## 使用 Speakeasy 生成示例 [#使用-speakeasy-生成示例]
</div>

如果你使用 [Speakeasy](https://www.speakeasy.com) 生成 SDK，可以将其自动生成的代码片段引入你的 API 参考文档，而无需手动维护。这些代码片段会与你的端点一起显示在[交互式演练场](/zh/api-playground/overview)中。

<Steps>
  <Step title="从注册表获取合并规范的 URL">
    前往你的 [Speakeasy 控制台](https://app.speakeasy.com)，打开 **API Registry** 标签页。打开你的 API 的 `*-with-code-samples` 条目。

    <Frame>
      ![Speakeasy API Registry 页面的屏幕截图。红色方框和数字 1 标出 API Registry 标签页，红色方框和数字 2 标出该 API 的条目。](/_assets/c467e4709030c41a7f746ea91cd2b5b064d6fb7135eb3278c8f61b0ae807ea1c)
    </Frame>

    <Note>
      如果该条目未标记为 **Combined Spec**，请确认你的 API 已配置[自动代码示例 URL](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls)。
    </Note>

    在注册表条目的页面中，复制提供的公开 URL。

    <Frame>
      ![屏幕截图显示合并规范的注册表条目，红色方框标出复制 URL 功能。](/_assets/628f1be1cb011cd63b8245b1829129061f06283dffb5fda4c7db7bd323522a61)
    </Frame>
  </Step>

  <Step title="将合并规范的 URL 添加到你的 `docs.json` 文件">
    将合并规范的 URL 添加到 `docs.json` 文件 `navigation` 对象中的 anchor 或标签页。

    <CodeGroup>
      <CodeBlockTabs defaultValue="Anchor" groupId="anchor+tab">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="Anchor">
            Anchor
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="Tab">
            Tab
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="Anchor">
          ```json  
          {
            "navigation": {
              "anchors": [
                {
                  "anchor": "API reference",
                  "icon": "square-terminal",
                  // !mark
                  "openapi": "SPEAKEASY_COMBINED_SPEC_URL"
                }
              ]
            }
          }
          ```
        </CodeBlockTab>

        <CodeBlockTab value="Tab">
          ```json  
          {
            "navigation": {
              "tabs": [
                {
                  "tab": "API reference",
                  // !mark
                  "openapi": "SPEAKEASY_COMBINED_SPEC_URL"
                }
              ]
            }
          }
          ```
        </CodeBlockTab>
      </CodeBlockTabs>
    </CodeGroup>
  </Step>

  <Step title="验证集成">
    重新部署文档后，在 API 参考中打开任意端点，确认演练场中显示了各语言的代码片段。可用语言的集合与你的 Speakeasy 项目中配置的 SDK 目标一致。

    如果代码片段未显示，请检查：

    * `docs.json` 中的 `openapi` URL 指向 `*-with-code-samples` 合并规范条目，而不是源 OpenAPI 文件。
    * 合并规范的 URL 可以从浏览器公开访问。
    * 你的 Speakeasy 项目已配置[自动代码示例 URL](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls)，并且至少启用了一个 SDK 目标。
  </Step>
</Steps>