API 试用台
在文档中直接测试 API 端点，填写参数、查看实时生成的代码示例，并发送真实请求。
API 试用台会在 API 端点页面添加交互式“Try it”按钮。开发者可以填写参数、查看实时更新的代码示例，并直接从文档页面发送真实的 HTTP 请求。
屏幕截图显示的是英文界面。
快速开始
试用台默认启用，无需配置 docs.json。每个包含 openapi: 或 api: 前置内容字段的页面都会显示“Try it”按钮。无需设置 CORS。
显示模式
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 前置内容字段，覆盖全局显示模式：
---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---此设置可用于全局关闭试用台、但在特定演示端点上启用，反之亦然。
| 前置内容 | 行为 |
|---|---|
playground: interactive | 在此页面启用完整试用台 |
playground: simple | 在此页面启用仅显示代码的试用台 |
playground: none | 在此页面不显示试用台 |
工作原理
试用台会以全屏弹窗覆盖层的形式打开，文档页面仍会完整显示在下方。
路径、查询、标头和正文参数会显示为表单字段。必填字段会标明。基础 URL 取自 OpenAPI 规范的 servers 字段。
代码示例会随着你的输入实时重新生成，适用于所有已配置的语言。只需单击一下即可复制任意示例。
在交互模式下，点击 Send（或按 Ctrl/Cmd+Enter）即可执行请求。响应会显示在下方，包括状态码、耗时和格式化后的正文。
试用台打开时，URL 会带上 ?playground=open。分享此 URL，即可直接打开某个端点的试用台视图。
多个服务器
如果端点的规范在 servers 下列出了多个条目（例如生产环境和沙盒环境），端点 URL 旁边会显示服务器选择器。读者的选择会设置基础 URL、复制 URL 按钮、页面上的代码示例，以及试用台发送的请求。
只有一个服务器的端点不会显示选择器，也不会增加页面负载。
键盘快捷键
| 快捷键 | 操作 |
|---|---|
Ctrl/Cmd + Enter | 发送请求 |
Escape | 关闭试用台 |
兼容两种 API 页面类型
试用台适用于使用 openapi: 或 api: 前置内容格式的页面：
Jamdesk 会从 OpenAPI 规范中提取参数和架构，无需进行任何设置。
---
openapi: POST /tickets
---本地开发
试用台仅在生产环境中运行。jamdesk dev 会显示“Try it”按钮。点击按钮后会显示简短通知，而不会打开弹窗。部署文档后即可使用完整的试用台。
在线试用
此站点已启用试用台。打开 OpenAPI 示例 页面，然后点击“Try it”，向演示 API 发送请求。