跳转到主要内容
每个端点页面都会在试验台旁边显示请求代码示例。默认情况下,Mintlify 会根据你的 OpenAPI 规范,以你选择的语言生成这些示例。如果你的用户通过 SDK 或 CLI 调用你的 API,可以使用 x-codeSamples 扩展添加你自己的示例,或从 Speakeasy 拉取示例。

选择示例语言

在 docs.json 中设置 api.examples.languages,选择生成的示例中显示哪些语言。语言按你列出的顺序显示。
docs.json
将 defaults 设置为 required,可在生成的示例中省略可选参数。默认值 all 会包含这些参数。
如果只想显示你编写的示例,请将 api.examples.autogenerate 设置为 false。这样,端点页面只会显示规范中的 x-codeSamples,或 MDX 页面上的 <RequestExample> 组件。

编写你自己的示例

将 x-codeSamples 属性添加到任意操作。它具有以下 schema。
string
必填
代码示例的语言。
string
示例的标签。当为同一个端点提供多个示例时非常有用。
string
必填
示例的源代码。
以下示例展示了一个植物管理应用的代码示例,该应用同时提供 Bash CLI 工具和 JavaScript SDK。

使用 Speakeasy 生成示例

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

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

前往你的 Speakeasy 控制台,打开 API Registry 标签页。打开你的 API 的 *-with-code-samples 条目。
Speakeasy API Registry 页面的屏幕截图。红色方框和数字 1 标出 API Registry 标签页,红色方框和数字 2 标出该 API 的条目。
如果该条目未标记为 Combined Spec,请确认你的 API 已配置自动代码示例 URL。
在注册表条目的页面中,复制提供的公开 URL。
2

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

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

验证集成

重新部署文档后,在 API 参考中打开任意端点,确认演练场中显示了各语言的代码片段。可用语言的集合与你的 Speakeasy 项目中配置的 SDK 目标一致。如果代码片段未显示,请检查:
  • docs.json 中的 openapi URL 指向 *-with-code-samples 合并规范条目,而不是源 OpenAPI 文件。
  • 合并规范的 URL 可以从浏览器公开访问。
  • 你的 Speakeasy 项目已配置自动代码示例 URL,并且至少启用了一个 SDK 目标。