API playground 是一个交互式环境，便于用户测试和探索你的 API 端点。开发者可以构造 API 请求、提交请求，并在不离开文档的情况下查看响应。
参见 触发更新 以查看 API playground 的实际效果。
Playground 会基于你的 OpenAPI 规范或 AsyncAPI 模式为端点生成交互式页面。若你修改了 API，Playground 会自动更新相关页面。
我们建议基于 OpenAPI 规范生成 API playground。或者，在你在 docs.json 中定义了基础 URL 和认证方式后，也可以手动创建 API 参考页面。
添加你的 OpenAPI 规范文件。
/your-project
|- docs.json
|- openapi.json
生成端点页面。
更新你的 docs.json 以引用 OpenAPI 规范。要为 OpenAPI 规范中的所有端点自动生成页面，请在任意导航元素中添加 openapi 属性。此示例会为 openapi.json 中指定的每个端点生成一个页面，并将这些页面归类到 “API reference” 组中。Generate all endpoint pages
"navigation": {
"groups": [
{
"group": "API reference",
"openapi": "openapi.json"
}
]
}
pages 属性中列出这些端点。此示例仅为 GET /users 和 POST /users 端点生成页面。若需生成其他端点页面，请将对应端点添加到 pages 数组中。Generate specific endpoint pages
"navigation": {
"groups": [
{
"group": "API reference",
"openapi": "openapi.json",
"pages": [
"GET /users",
"POST /users"
]
}
]
}
docs.json 中定义以下属性，以自定义 API 操作台。
API 操作台的配置。
display
"interactive" | "simple" | "none" | "auth"
API 操作台的显示模式。
"interactive"：显示交互式 playground。"simple"：显示可复制的端点，不显示 playground。"none"：不显示任何内容。"auth"：仅向已通过身份验证的用户显示交互式 playground。未通过身份验证的用户或不在所需组中的用户将看不到 playground。
默认为 interactive。 是否通过代理服务器转发 API 请求。默认为 true。
端点标头中 base URL 的显示模式。设置为 full 时，每个端点页面都会显示完整的 base URL。默认情况下，仅显示相对端点路径。
自动生成的 API 示例的配置。
自动生成的 API 代码片段所使用的示例语言。语言按指定顺序显示。
| 显示名称 | 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 |
是否在 API 示例中显示可选参数。默认为 all。
是否使用 schema 示例中的数据预填 API 操作台。启用后，playground 会根据 OpenAPI 规范中的示例值自动填充请求字段。默认为 false。
是否根据 API 规范为端点生成代码示例。默认为 true。当设置为 false 时，API 操作台中只会显示手动编写的代码示例 (来自 OpenAPI 规范中的 x-codeSamples 或 MDX 中的 <RequestExample> 组件) 。
{
"api": {
"playground": {
"display": "interactive"
},
"examples": {
"languages": ["curl", "python", "javascript"],
"defaults": "required",
"prefill": true
}
}
}
auth 显示模式，仅向已通过认证的用户显示交互式 playground。这样可以在公开展示 API 文档的同时，将 playground 的使用限制在已登录用户范围内。
当 display 设置为 auth 时：
- 已认证用户会看到交互式 playground。
- 未认证用户不会看到 playground (等同于
none) 。
你也可以将 auth 与页面 frontmatter 中的 groups 属性结合使用，仅向特定用户组开放 playground 访问权限。
Page with group-restricted playground
---
title: "创建用户"
openapi: POST /users
playground: auth
groups: ["admin", "developer"]
public: true
---
- 页面对所有人公开可见 (任何人都可以查看文档) 。
- 只有属于
admin 或 developer groups 的已认证用户才能看到交互式 playground。
- 不属于这些 groups 的用户不会看到 playground。
如果页面没有 groups 属性，所有已认证用户都会看到交互式 playground。
当你需要对 API 文档进行更精细的控制时，可以在 OpenAPI 规范中使用 x-mint 扩展，或者为各个 endpoint 创建单独的 MDX 页面。
这两种方式都可以让你：
- 自定义页面 metadata
- 添加示例等额外内容
- 按页面控制 playground 的行为
推荐使用 x-mint 扩展，这样你的所有 API 文档都可以从 OpenAPI 规范中自动生成，并集中维护在一个文件中。
对于小型 API，或者当你希望在单个页面上逐页试验更改时，推荐使用单独的 MDX 页面。
