x-codeSamples 扩展添加你自己的示例,或从 Speakeasy 拉取示例。
在 docs.json 中设置 api.examples.languages,选择生成的示例中显示哪些语言。语言按你列出的顺序显示。
docs.json
defaults 设置为 required,可在生成的示例中省略可选参数。默认值 all 会包含这些参数。
所有支持的语言
所有支持的语言
api.examples.autogenerate 设置为 false。这样,端点页面只会显示规范中的 x-codeSamples,或 MDX 页面上的 <RequestExample> 组件。
将 x-codeSamples 属性添加到任意操作。它具有以下 schema。
以下示例展示了一个植物管理应用的代码示例,该应用同时提供 Bash CLI 工具和 JavaScript SDK。
1
从注册表获取合并规范的 URL
前往你的 Speakeasy 控制台,打开 API Registry 标签页。打开你的 API 的 
在注册表条目的页面中,复制提供的公开 URL。
*-with-code-samples 条目。
如果该条目未标记为 Combined Spec,请确认你的 API 已配置自动代码示例 URL。
2
将合并规范的 URL 添加到你的 docs.json 文件
将合并规范的 URL 添加到
docs.json 文件 navigation 对象中的 anchor 或标签页。3
验证集成
重新部署文档后,在 API 参考中打开任意端点,确认演练场中显示了各语言的代码片段。可用语言的集合与你的 Speakeasy 项目中配置的 SDK 目标一致。如果代码片段未显示,请检查:
docs.json中的openapiURL 指向*-with-code-samples合并规范条目,而不是源 OpenAPI 文件。- 合并规范的 URL 可以从浏览器公开访问。
- 你的 Speakeasy 项目已配置自动代码示例 URL,并且至少启用了一个 SDK 目标。