API 调试台
在文档中直接测试 API 端点，填写参数、查看实时代码示例并发送真实请求。
API 调试台会在 API 端点页面添加交互式的“Try it”按钮。开发者可以填写参数，实时查看代码示例更新，并直接从文档页面发送真实的 HTTP 请求。
屏幕截图显示的是英文界面。
快速开始
调试台默认启用。任何包含 openapi: 或 api: frontmatter 字段的页面都会自动显示“Try it”按钮。CORS 会自动处理。
无需配置 docs.json。在页面 frontmatter 中添加 openapi: 或 api: 字段，调试台就会显示。
显示模式
display 字段控制调试台的功能：
| 模式 | “Try it”按钮 | 填写参数 | 实时代码 | 发送请求 |
|---|---|---|---|---|
"interactive"（默认） | ✓ | ✓ | ✓ | ✓ |
"simple" | ✓ | ✓ | ✓ | ✗ |
"none" | ✗ | ✗ | ✗ | ✗ |
完整的调试台体验。开发者可以填写参数，实时查看代码示例更新，并发送真实的 HTTP 请求。响应会以内嵌方式显示，包括状态代码、耗时和格式化的请求正文。
{
"api": {
"playground": {
"display": "interactive"
}
}
}身份验证
如果 API 需要身份验证（通过 docs.json 中的 api.mdx.auth.method 配置），调试台会在参数表单顶部显示身份验证输入字段。开发者可以直接在弹窗中输入 API 密钥或令牌。
凭据仅在当前会话中保存在内存中。它们不会保存到 localStorage，也不会在多次访问之间持久化。
预填充示例值
当 OpenAPI 规范在参数和请求正文中包含 example 值时，调试台可以预填充这些值：
{
"api": {
"examples": {
"prefill": true
}
}
}这样可以显示开发者能够修改的真实值，而不是从空字段开始，从而节省时间。
按页面覆盖设置
使用 playground frontmatter 字段，在单个页面上覆盖全局显示模式：
---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---当你希望全局禁用调试台、但在特定演示端点上启用，或反过来时，这项设置非常有用。
| Frontmatter | 行为 |
|---|---|
playground: interactive | 在此页面启用完整调试台 |
playground: simple | 在此页面启用仅代码调试台 |
playground: none | 在此页面不显示调试台 |
工作原理
调试台会以全屏弹窗覆盖层的形式打开。你的文档页面会完整保留在下方。
路径、查询、标头和正文参数会显示为表单字段。必填字段会进行标记。基础 URL 来自 OpenAPI 规范的 servers 字段。
输入内容时，所有已配置语言的代码示例都会实时重新生成。点击一次即可复制任意示例。
在交互模式下，点击 Send（或按 Ctrl/Cmd+Enter）即可执行请求。响应会显示在下方，包括状态代码、持续时间和格式化的请求正文。
打开调试台时，URL 会更新为包含 ?playground=open。分享此 URL，即可让他人直接打开某个端点的调试台视图。
多个服务器
当端点的规范在 servers 下列出多个条目（例如生产环境和沙盒环境）时，端点 URL 旁边会显示服务器选择器。读者选择的服务器会决定基础 URL、复制 URL 按钮、页面上的代码示例，以及调试台实际发送的请求，因此不会有人在阅读沙盒文档时复制生产环境的 curl 命令。
只有一个服务器的端点保持不变：没有选择器，也不会增加页面负载。
键盘快捷键
| 快捷键 | 操作 |
|---|---|
Ctrl/Cmd + Enter | 发送请求 |
Escape | 关闭调试台 |
兼容两种 API 页面类型
调试台支持使用 openapi: 或 api: frontmatter 格式的页面：
参数和架构会自动从 OpenAPI 规范中提取。无需其他设置。
---
openapi: POST /tickets
---本地开发
运行 jamdesk dev 时，“Try it”按钮会显示，但调试台本身仅适用于生产环境。在本地开发环境中点击“Try it”会显示简短通知，而不是打开弹窗。部署文档后即可使用完整的调试台。
在线试用
此文档站点已启用调试台。访问 OpenAPI 示例 页面，然后点击“Try it”，即可通过演示 API 查看其运行效果。