docs.json 中的 api.playground 对象。
在 OpenAPI 规范中添加包含 API 基础 URL 的 servers 字段。试验台会将每个端点的路径(例如 /users/{id})追加到此 URL 之后。
simple 模式显示端点。
如果你的 API 从不同的 URL 提供某些端点,请为某个路径或操作覆盖 servers 字段。有关 servers 字段的更多信息,请参阅 OpenAPI 文档中的 API server and base path。
使用 OpenAPI 规范中的 securitySchemes 和 security 字段定义读者的身份验证方式。试验台会为每个方案添加一个输入框,以便读者在发送请求前输入凭据。
1
定义你的身份验证方法。
添加
securitySchemes 字段。此示例定义了 bearer 身份验证。2
将身份验证应用到你的端点。
添加
security 字段以要求使用该方案。security 字段。有关更多信息,请参阅 OpenAPI 文档中的 Authentication。
试验台会根据安全方案类型为授权字段生成描述。要将其替换为你自己的文本(例如说明读者在哪里找到密钥),请为安全方案添加 description。该描述支持 Markdown,并应用于使用该方案的每个端点。
x-default 扩展,即可在试验台中预填其输入框,例如使用占位符或测试凭据。x-default 适用于 apiKey 和 http bearer 方案。
security 字段列出了 scopes,端点页面会在授权部分之后的 Scopes 部分中显示它们。试验台也会在所选授权选项的输入框下方列出它们。
security 字段中每个选项的 scopes,因此无论读者选择哪个授权选项都能看到它们。在此示例中,即使 apiToken 是第一个选项,users:read 也会显示。
- scope 描述来自 OAuth 2.0 方案
flows中的scopes映射。 - 在 OpenAPI 3.1 中,
apiKey和http要求上的角色列表(例如{ "apiKey": ["admin"] })也会出现在同一部分。 - 如果有多个方案需要 scopes,每个 scope 旁边的标签会显示其方案名称。
docs.json 中设置 api.playground.display,控制每个端点页面上显示的内容:
interactive(默认):完整的试验台。simple:可复制的端点,不显示试验台。none:不显示试验台。auth:已登录的读者看到完整的试验台,其他人什么也看不到。请参阅仅向已登录的读者显示试验台。
docs.json
playground,对于生成的页面则在 x-mint.metadata 中设置。
auth 显示模式,可以在保持 API 参考公开的同时,只允许已登录的读者发送请求。auth 模式要求你的站点启用身份验证。
要将试验台限制为特定用户组,请在页面 frontmatter 中添加 groups。如果页面没有 groups,所有已登录的读者都能看到试验台。
admin 或 developer 组的已登录读者才能看到试验台。
对于生成的页面,请在 x-mint.metadata 中设置相同的字段:
api.playground.proxy 设置为 false,即可让请求直接从读者的浏览器发送到你的 API。如果你的 API 需要代理无法转发的 header,或者请求必须来自读者的浏览器(例如基于 cookie 的身份验证),请这样设置。此时你的 API 必须通过 CORS 允许来自文档域名的跨源请求。
要在直接请求中发送 cookie、授权 header 和 TLS 客户端证书,还需将 credentials 设置为 true。
docs.json
/_mintlify/api/request 路径的 POST 请求。启用 Mintlify 代理时,试验台会将每个请求作为 POST 发送到该路径。如果你的反向代理无法允许 POST 请求,请将 proxy 设置为 false。
要使用 OpenAPI 规范中的示例值填充请求字段,请在 docs.json 中将 api.examples.prefill 设置为 true。
docs.json
default 不同的值预填某个字段,请为该属性添加 x-default。属性上的 x-default 仅在 prefill 为 true 时生效。安全方案上的 x-default 始终生效。
有关试验台设置的完整列表,请参阅 API 设置。