mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
4b465465dd
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
268 lines
10 KiB
Plaintext
268 lines
10 KiB
Plaintext
---
|
||
title: "操作台"
|
||
description: "让开发者在文档中直接测试 API 端点，交互式演练场可发送真实请求并显示响应结果。"
|
||
keywords: ["交互式", "API", "端点测试", "实时 API 请求", "请求构造器"]
|
||
boost: 3
|
||
---
|
||
|
||
API playground 是一个交互式环境，便于用户测试和探索你的 API 端点。开发者可以构造 API 请求、提交请求，并在不离开文档的情况下查看响应。
|
||
|
||
参见 [触发更新](/zh/api/update/trigger) 以查看 API playground 的实际效果。
|
||
|
||
<Frame>
|
||
<img src="/images/playground/API-playground-light.png" alt="用于“触发更新”端点的 API playground。" className="block dark:hidden" />
|
||
|
||
<img src="/images/playground/API-playground-dark.png" alt="用于“触发更新”端点的 API playground。" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
Playground 会基于你的 OpenAPI 规范或 AsyncAPI 模式为端点生成交互式页面。若你修改了 API，Playground 会自动更新相关页面。
|
||
|
||
我们建议基于 OpenAPI 规范生成 API playground。或者，在你在 `docs.json` 中定义了基础 URL 和认证方式后，也可以手动创建 API 参考页面。
|
||
|
||
<div id="get-started">
|
||
## 入门
|
||
</div>
|
||
|
||
<Steps>
|
||
<Step title="添加你的 OpenAPI 规范文件。">
|
||
<Tip>
|
||
使用 [Swagger Editor](https://editor.swagger.io/) 或 [Mint CLI](https://www.npmjs.com/package/mint) 命令 `mint validate` 验证你的 OpenAPI 规范文件。
|
||
</Tip>
|
||
|
||
```bash {3}
|
||
/your-project
|
||
|- docs.json
|
||
|- openapi.json
|
||
```
|
||
</Step>
|
||
|
||
<Step title="生成端点页面。">
|
||
更新你的 `docs.json` 以引用 OpenAPI 规范。
|
||
|
||
**要为 OpenAPI 规范中的所有端点自动生成页面**，请在任意导航元素中添加 `openapi` 属性。
|
||
|
||
此示例会为 `openapi.json` 中指定的每个端点生成一个页面，并将这些页面归类到 “API reference” 组中。
|
||
|
||
```json Generate all endpoint pages
|
||
"navigation": {
|
||
"groups": [
|
||
{
|
||
"group": "API reference",
|
||
"openapi": "openapi.json"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**若只为特定端点生成页面**，请在该导航元素的 `pages` 属性中列出这些端点。
|
||
|
||
此示例仅为 `GET /users` 和 `POST /users` 端点生成页面。若需生成其他端点页面，请将对应端点添加到 `pages` 数组中。
|
||
|
||
```json Generate specific endpoint pages
|
||
"navigation": {
|
||
"groups": [
|
||
{
|
||
"group": "API reference",
|
||
"openapi": "openapi.json",
|
||
"pages": [
|
||
"GET /users",
|
||
"POST /users"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
</Step>
|
||
</Steps>
|
||
|
||
<div id="customize-your-playground">
|
||
## 自定义您的 API 操作台
|
||
</div>
|
||
|
||
在 `docs.json` 中定义以下属性，以自定义您的 API 操作台。
|
||
|
||
<ResponseField name="playground" type="object">
|
||
API 操作台的配置。
|
||
|
||
<Expandable title="playground" defaultOpen="True">
|
||
<ResponseField name="display" type=""interactive" | "simple" | "none" | "auth"">
|
||
API 操作台的显示模式。
|
||
|
||
* `"interactive"`：显示交互式 API 操作台。
|
||
* `"simple"`：显示可复制的端点，不显示 API 操作台。
|
||
* `"none"`：不显示任何内容。
|
||
* `"auth"`：仅向已认证用户显示交互式 API 操作台。未认证用户或不在所需组中的用户将看不到 API 操作台。
|
||
|
||
默认为 `interactive`。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="proxy" type="boolean" defaultOpen="True">
|
||
是否通过 Mintlify 的代理服务器转发 API 请求。默认为 `true`。
|
||
|
||
当设置为 `true` 时，playground 请求会通过 Mintlify 的服务器路由。当设置为 `false` 时，playground 会直接从浏览器向你的 API 发送请求。当你的 API 接受浏览器直接请求且不需要 Mintlify 代理流量时，请设置为 `false`。例如，当你的 API 需要无法通过代理转发的特定请求头时，或者当你需要请求直接从用户浏览器发起以进行身份验证时。
|
||
</ResponseField>
|
||
<ResponseField name="credentials" type="boolean">
|
||
当 `proxy` 为 `false` 时，是否在跨域请求中包含 cookies、授权头和 TLS 客户端证书。默认为 `false`。
|
||
|
||
当为 `true` 且 `proxy` 为 `false` 时，playground 会在发送请求时附带浏览器管理的凭据。例如，当你的 API 使用基于 cookie 的身份验证或 HTTP 会话令牌时。
|
||
|
||
当 `proxy` 为 `true` 时，此选项无效。
|
||
</ResponseField>
|
||
</Expandable>
|
||
</ResponseField>
|
||
|
||
<ResponseField name="url" type=""full"">
|
||
端点标头中 base URL 的显示模式。设置为 `full` 时，每个端点页面都会显示完整的 base URL。默认情况下，仅显示相对端点路径。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="examples" type="object">
|
||
自动生成的 API 示例的配置。
|
||
|
||
<Expandable title="examples" defaultOpen="True">
|
||
<ResponseField name="languages" type="array of string">
|
||
自动生成的 API 代码片段所使用的示例语言。
|
||
|
||
语言按指定顺序显示。
|
||
|
||
<Accordion title="所有支持的语言">
|
||
| 显示名称 | Key | 别名 |
|
||
| --- | --- | --- |
|
||
| cURL | `bash` | `curl`, `sh`, `shell` |
|
||
| Python | `python` | `py` |
|
||
| JavaScript | `javascript` | `js` |
|
||
| Node.js | `node` | `nodejs`, `node.js` |
|
||
| PHP | `php` | |
|
||
| Go | `go` | `golang` |
|
||
| Java | `java` | |
|
||
| Ruby | `ruby` | `rb` |
|
||
| PowerShell | `powershell` | |
|
||
| Swift | `swift` | |
|
||
| C# | `csharp` | `c#` |
|
||
| .NET | `dotnet` | `.net`, `.NET`, `dot-net` |
|
||
| TypeScript | `typescript` | `ts` |
|
||
| C | `c` | |
|
||
| C++ | `c++` | `cpp` |
|
||
| Kotlin | `kotlin` | `kt` |
|
||
| Rust | `rust` | `rs` |
|
||
| Dart | `dart` | `flutter` |
|
||
</Accordion>
|
||
</ResponseField>
|
||
|
||
<ResponseField name="defaults" type=""required" | "all"">
|
||
是否在 API 示例中显示可选参数。默认为 `all`。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="prefill" type="boolean">
|
||
是否使用 schema 示例中的数据预填 API 操作台。启用后，API 操作台会根据 OpenAPI 规范中的示例值自动填充请求字段。默认为 `false`。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="autogenerate" type="boolean">
|
||
是否根据 API 规范为端点生成代码示例。默认为 `true`。当设置为 `false` 时，API 操作台中只会显示手动编写的代码示例 (来自 OpenAPI 规范中的 `x-codeSamples` 或 MDX 中的 `<RequestExample>` 组件) 。
|
||
</ResponseField>
|
||
</Expandable>
|
||
</ResponseField>
|
||
|
||
<div id="example-configuration">
|
||
### 配置示例
|
||
</div>
|
||
|
||
此示例将 API playground 配置为可交互，并提供 cURL、Python 和 JavaScript 的示例代码片段。它仅在代码片段中显示必填参数，且 playground 会为请求体预填示例值。
|
||
|
||
```json
|
||
{
|
||
"api": {
|
||
"playground": {
|
||
"display": "interactive"
|
||
},
|
||
"examples": {
|
||
"languages": ["curl", "python", "javascript"],
|
||
"defaults": "required",
|
||
"prefill": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
<div id="auth-based-playground-display">
|
||
### 基于认证的 playground 显示
|
||
</div>
|
||
|
||
使用 `auth` 显示模式，仅向已通过认证的用户显示交互式 playground。这样可以在公开展示 API 文档的同时，将 playground 的使用限制在已登录用户范围内。
|
||
|
||
当 `display` 设置为 `auth` 时：
|
||
|
||
* 已认证用户会看到交互式 playground。
|
||
* 未认证用户不会看到 playground (等同于 `none`) 。
|
||
|
||
你也可以将 `auth` 与页面 frontmatter 中的 `groups` 属性结合使用，仅向特定用户组开放 playground 访问权限。
|
||
|
||
```mdx Page with group-restricted playground
|
||
---
|
||
title: "创建用户"
|
||
openapi: POST /users
|
||
playground: auth
|
||
groups: ["admin", "developer"]
|
||
public: true
|
||
---
|
||
```
|
||
|
||
在本示例中：
|
||
|
||
* 页面对所有人公开可见 (任何人都可以查看文档) 。
|
||
* 只有属于 `admin` 或 `developer` groups 的已认证用户才能看到交互式 playground。
|
||
* 不属于这些 groups 的用户不会看到 playground。
|
||
|
||
如果页面没有 `groups` 属性，所有已认证用户都会看到交互式 playground。
|
||
|
||
<Note>
|
||
`auth` 显示模式要求你的文档已配置好[认证](/zh/deploy/authentication-setup)。
|
||
</Note>
|
||
|
||
<div id="custom-endpoint-pages">
|
||
### 自定义 endpoint 页面
|
||
</div>
|
||
|
||
当你需要对 API 文档进行更精细的控制时，可以在 OpenAPI 规范中使用 `x-mint` 扩展，或者为各个 endpoint 创建单独的 MDX 页面。
|
||
|
||
这两种方式都可以让你：
|
||
|
||
* 自定义页面 metadata
|
||
* 添加示例等额外内容
|
||
* 按页面控制 playground 的行为
|
||
|
||
我们推荐使用 `x-mint` 扩展，这样你的所有 API 文档都可以从 OpenAPI 规范中自动生成，并集中维护在一个文件中。
|
||
|
||
对于小型 API，或者当你希望在单个页面上逐页试验更改时，我们推荐使用单独的 MDX 页面。
|
||
|
||
<div id="response-rendering">
|
||
## 响应渲染
|
||
</div>
|
||
|
||
Playground 会根据 API 返回的 `Content-Type` 响应头自动渲染响应。
|
||
|
||
- **图片**：内联渲染 (`image/*`)。
|
||
- **音频**：使用内置音频播放器渲染 (`audio/*`)。
|
||
- **视频**：使用内置视频播放器渲染 (`video/*`)。任何 `video/*` 类型的响应，如 `video/mp4` 或 `video/webm`，都会在 playground 中直接显示为可播放的视频。
|
||
- **所有其他响应**：在代码块中显示。
|
||
|
||
<div id="parameter-anchor-links">
|
||
## 参数锚点链接
|
||
</div>
|
||
|
||
API playground 中的每个参数都有一个可点击的锚点链接。将鼠标悬停在参数名称上以显示链接图标，然后点击即可复制该参数的直接链接。
|
||
|
||
使用参数锚点链接可以：
|
||
- 在技术支持对话或文档中分享指向特定参数的链接
|
||
- 从其他页面或外部资源直接跳转到某个参数
|
||
- 将常用参数添加到书签
|
||
|
||
URL 格式为 `你的文档网址/端点路径#参数名称`。对于嵌套参数，锚点会包含父级路径。
|
||
|
||
<div id="further-reading">
|
||
## 延伸阅读
|
||
</div>
|
||
|
||
* [OpenAPI 设置](/zh/api-playground/openapi-setup)，详细了解如何创建 OpenAPI 文档。
|
||
* [x-mint 扩展](/zh/api-playground/openapi-setup#customize-your-endpoint-pages)，详细了解如何自定义端点页面。
|
||
* [MDX 设置](/zh/api-playground/mdx-setup)，详细了解如何手动创建单个 API 参考页面。
|
||
* [AsyncAPI 设置](/zh/api-playground/asyncapi-setup)，详细了解如何创建 AsyncAPI 模式以生成 WebSocket 参考页面。 |