添加 SDK 示例
使用 x-codeSamples OpenAPI 扩展为你的 API 文档添加 SDK 代码示例，或通过 Speakeasy 自动添加。
如果你的用户通过 SDK 而非直接的网络请求与 API 交互，请使用 x-codeSamples 扩展添加 SDK 代码示例。Mintlify 会在你的 OpenAPI 页面上显示这些示例。
你可以自行编写这些示例。如果你使用 Speakeasy 生成 SDK，Speakeasy 可以自动将示例添加到你的规范中。
将 x-codeSamples 属性添加到任意请求方法。它具有以下 schema。
langstringrequired代码示例的语言。
labelstring示例的标签。当为同一个端点提供多个示例时非常有用。
sourcestringrequired示例的源代码。
以下示例展示了一个植物管理应用的代码示例，该应用同时提供 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 生成 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"
}
]
}
}验证集成
重新部署文档后，在 API 参考中打开任意端点，确认演练场中显示了各语言的代码片段。可用语言的集合与你的 Speakeasy 项目中配置的 SDK 目标一致。
如果代码片段未显示，请检查：
docs.json中的openapiURL 指向*-with-code-samples合并规范条目，而不是源 OpenAPI 文件。- 合并规范的 URL 可以从浏览器公开访问。
- 你的 Speakeasy 项目已配置自动代码示例 URL，并且至少启用了一个 SDK 目标。