添加 SDK 示例

如果你的用户通过 SDK 而非直接的网络请求与 API 交互，请使用 x-codeSamples 扩展添加 SDK 代码示例。Mintlify 会在你的 OpenAPI 页面上显示这些示例。你可以自行编写这些示例；如果你使用 Speakeasy 生成 SDK，也可以让示例自动添加到你的规范中。

手动添加示例

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

string

必填

代码示例的语言。

string

示例的标签。当为同一个端点提供多个示例时非常有用。

string

必填

示例的源代码。

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

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 });

使用 Speakeasy 生成示例

如果你使用 Speakeasy 生成 SDK，可以将其自动生成的代码片段引入你的 API 参考文档，而无需手动维护。这些代码片段会与你的端点一起显示在交互式演练场中。

从注册表获取合并规范的 URL

前往你的 Speakeasy 控制台，打开 API Registry 标签页。打开该 API 的 *-with-code-samples 条目。

如果该条目未标记为 Combined Spec，请确认该 API 已配置自动代码示例 URL。

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

将合并规范的 URL 添加到你的 docs.json 文件

将合并规范的 URL 添加到 docs.json 文件 navigation 对象中的 anchor 或标签页。

{
  "navigation": {
    "anchors": [
      {
        "anchor": "API reference",
        "icon": "square-terminal",
        // !mark
        "openapi": "SPEAKEASY_COMBINED_SPEC_URL"
      }
    ]
  }
}

{
  "navigation": {
    "tabs": [
      {
        "tab": "API reference",
        // !mark
        "openapi": "SPEAKEASY_COMBINED_SPEC_URL"
      }
    ]
  }
}

验证集成

重新部署文档后，在 API 参考中打开任意端点，确认演练场中显示了各语言的代码片段。可用语言的集合与你的 Speakeasy 项目中配置的 SDK 目标一致。如果代码片段未显示，请检查：

docs.json 中的 openapi URL 指向 *-with-code-samples 合并规范条目，而不是源 OpenAPI 文件。
合并规范的 URL 可以从浏览器公开访问。
你的 Speakeasy 项目已配置自动代码示例 URL，并且至少启用了一个 SDK 目标。

快速入门

创建内容

管理站点

Agent

Assistant

面向 Agent 的内容

搜索与 SEO

编写 API 文档

集成

参考

添加 SDK 示例

手动添加示例

使用 Speakeasy 生成示例

​手动添加示例

​使用 Speakeasy 生成示例

手动添加示例

使用 Speakeasy 生成示例