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，即可让他人直接打开某个端点的试用台视图。
键盘快捷键
| 快捷键 | 操作 |
|---|---|
Ctrl/Cmd + Enter | 发送请求 |
Escape | 关闭试用台 |
同时支持两种 API 页面类型
试用台支持使用 openapi: 或 api: frontmatter 格式的页面：
参数和架构会自动从 OpenAPI 规范中获取。无需额外设置。
---
openapi: POST /tickets
---本地开发
运行 jamdesk dev 时，“Try it”按钮会显示，但试用台本身仅支持生产环境。在本地开发环境中点击“Try it”会显示简短通知，而不会打开模态窗口。部署文档后即可使用完整试用台。
在线试用
此文档站点已启用试用台。访问 OpenAPI Example 页面，然后点击“Try it”，通过演示 API 查看其实际效果。