mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
b34afc88b6
* docs: fix es/fr/zh translation lag and add missing zh workflows redirects * docs: SEO metadata fixes and HTML entity cleanup in touched locale pages --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
130 lines
4.2 KiB
Plaintext
130 lines
4.2 KiB
Plaintext
---
|
||
title: "添加 SDK 示例"
|
||
description: "使用 x-codeSamples OpenAPI 扩展为你的 API 文档添加 SDK 代码示例，或通过 Speakeasy 自动添加。"
|
||
keywords: ["x-codeSamples", "SDK 示例", "Speakeasy", "自动生成的 SDK"]
|
||
---
|
||
|
||
如果你的用户通过 SDK 而非直接的网络请求与 API 交互，请使用 `x-codeSamples` 扩展添加 SDK 代码示例。Mintlify 会在你的 OpenAPI 页面上显示这些示例。
|
||
|
||
你可以自行编写这些示例。如果你使用 Speakeasy 生成 SDK，Speakeasy 可以自动将示例添加到你的规范中。
|
||
|
||
<div id="add-examples-manually">
|
||
## 手动添加示例
|
||
</div>
|
||
|
||
将 `x-codeSamples` 属性添加到任意请求方法。它具有以下 schema。
|
||
|
||
<ParamField body="lang" type="string" required>
|
||
代码示例的语言。
|
||
</ParamField>
|
||
|
||
<ParamField body="label" type="string">
|
||
示例的标签。当为同一个端点提供多个示例时非常有用。
|
||
</ParamField>
|
||
|
||
<ParamField body="source" type="string" required>
|
||
示例的源代码。
|
||
</ParamField>
|
||
|
||
以下示例展示了一个植物管理应用的代码示例，该应用同时提供 Bash CLI 工具和 JavaScript SDK。
|
||
|
||
```yaml
|
||
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 });
|
||
```
|
||
|
||
<div id="generate-examples-with-speakeasy">
|
||
## 使用 Speakeasy 生成示例
|
||
</div>
|
||
|
||
如果你使用 [Speakeasy](https://www.speakeasy.com) 生成 SDK，可以将其自动生成的代码片段引入你的 API 参考文档，而无需手动维护。这些代码片段会与你的端点一起显示在[交互式演练场](/zh/api-playground/overview)中。
|
||
|
||
<Steps>
|
||
<Step title="从注册表获取合并规范的 URL">
|
||
|
||
前往你的 [Speakeasy 控制台](https://app.speakeasy.com)，打开 **API Registry** 标签页。打开你的 API 的 `*-with-code-samples` 条目。
|
||
|
||
<Frame>
|
||
|
||
</Frame>
|
||
|
||
<Note>
|
||
如果该条目未标记为 **Combined Spec**，请确认你的 API 已配置[自动代码示例 URL](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls)。
|
||
</Note>
|
||
|
||
在注册表条目的页面中，复制提供的公开 URL。
|
||
|
||
<Frame>
|
||
|
||
</Frame>
|
||
</Step>
|
||
<Step title="将合并规范的 URL 添加到你的 `docs.json` 文件">
|
||
|
||
将合并规范的 URL 添加到 `docs.json` 文件 `navigation` 对象中的 anchor 或标签页。
|
||
|
||
<CodeGroup>
|
||
|
||
```json title="Anchor"
|
||
{
|
||
"navigation": {
|
||
"anchors": [
|
||
{
|
||
"anchor": "API reference",
|
||
"icon": "square-terminal",
|
||
// !mark
|
||
"openapi": "SPEAKEASY_COMBINED_SPEC_URL"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
```json title="Tab"
|
||
{
|
||
"navigation": {
|
||
"tabs": [
|
||
{
|
||
"tab": "API reference",
|
||
// !mark
|
||
"openapi": "SPEAKEASY_COMBINED_SPEC_URL"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
</Step>
|
||
<Step title="验证集成">
|
||
|
||
重新部署文档后，在 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 目标。
|
||
|
||
</Step>
|
||
</Steps>
|