# Speakeasy (/zh/integrations/sdks/speakeasy)

<!-- agent-signals: reading_time_min: 1 · est_tokens: 627 · updated: 2026-07-31 -->
Related: [Stainless](/zh/integrations/sdks/stainless.md), [Segment](/zh/integrations/analytics/segment.md)

你可以将来自 Speakeasy SDK 的自动生成代码片段直接集成到 Mintlify 的 API 参考文档中。这些 SDK 使用示例将显示在由 Mintlify 驱动的文档站点的[交互式操作台](/zh/api-playground/overview)中。

<Frame>
  ![带有 Speakeasy 代码片段的 Mintlify API 操作台。](/_assets/db0c643b079164f9326cdc8153a2adaa40d6dbe716739f4e3fffa503bd6919aa)
</Frame>

<div id="prerequisites">
  ## 前提条件 [#前提条件]
</div>

要将 Mintlify 与 Speakeasy 集成，你需要：

* 一个 [Mintlify 文档存储库](/zh/quickstart)。
  * 一个由 Speakeasy 生成的 SDK，并已配置[自动代码示例 URL](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls)。

<div id="setting-up-the-integration">
  ## 设置集成 [#设置集成]
</div>

要将 Speakeasy 与 Mintlify 集成，你需要从注册中心获取该 API 的合并规范的公共 URL，并更新你的 `docs.json` 配置文件。

<div id="get-the-apis-combined-spec-public-url-from-the-registry">
  ### 从注册表获取 API 的合并规范公开 URL [#从注册表获取-api-的合并规范公开-url]
</div>

前往你的 [Speakeasy 控制台](https://app.speakeasy.com)，打开 **API Registry** 标签页。打开该 API 的 `*-with-code-samples` 条目。

<Frame>
  ![Speakeasy API Registry 页面截图。API Registry 标签页以红色方框和数字 1 标注，API 的条目以红色方框和数字 2 标注。](/_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>

<div id="update-your-docsjson-configuration-file">
  ### 更新你的 `docs.json` 配置文件 [#更新你的-docsjson-配置文件]
</div>

将合并后的规范 URL 添加到 `docs.json` 文件中的 **Anchors** 或 **Tabs** 部分。

在 `docs.json` 文件中按如下方式更新 `anchor` 字段，将合并后的规范 URL 添加到对应锚点：

```json title="docs.json"
{
  "anchors": [
    {
      "name": "API Reference",
      // !mark
      "openapi": "SPEAKEASY_COMBINED_SPEC_URL",
      "url": "api-reference",
      "icon": "square-terminal"
    }
  ]
}
```

通过如下方式在 `docs.json` 文件中更新 `tab` 字段，将合并后的规范 URL 添加到一个标签页中：

```json title="docs.json"
{
  "tabs": [
    {
      "name": "API Reference",
      "url": "api-reference",
      // !mark
      "openapi": "SPEAKEASY_COMBINED_SPEC_URL"
    }
  ]
}
```

现在，你可以在 API 文档中查看 Speakeasy 生成的代码片段，并在演示区中与它们交互。

<div id="verify-the-integration">
  ## 验证集成 [#验证集成]
</div>

重新部署文档后，打开 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 目标。