使用 docs.json 中的 api 字段来配置可用于生成 API 页面的 API 规范；用户可以测试 API 端点的交互式 API 演练场；以及如何生成和显示代码示例。
api
类型： object
在 api 键下定义所有与 API 相关的设置。
用于生成 API 参考页面的 OpenAPI 规范文件。接受单个路径或 URL、路径和 URL 数组，或指定 source 和 directory 的对象。
你的 OpenAPI 规范文件的 URL 或路径。最小长度：1。
搜索 OpenAPI 文件的目录。开头不要包含斜杠。
"openapi": "openapi.json"
用于生成事件驱动 API 参考页面的 AsyncAPI 规范文件。接受单个路径或 URL、路径和 URL 数组，或指定 source 和 directory 的对象。
你的 AsyncAPI 规范文件的 URL 或路径。最小长度：1。
搜索 AsyncAPI 文件的目录。开头不要包含斜杠。
"asyncapi": "asyncapi.json"
交互式 API 演练场设置。
display
"interactive" | "simple" | "none" | "auth"
演练场的显示模式。默认为 interactive。
interactive — 完整的交互式演练场，带请求构建器simple — 简化视图，不带请求构建器none — 完全隐藏演练场auth — 仅向已认证用户显示演练场
是否通过代理服务器路由 API 请求。默认为 true。
端点标题中基础 URL 的显示模式。设置为 full 可始终在每个端点页面显示完整的基础 URL。默认情况下，仅当有多个基础 URL 可选择时才显示基础 URL。
自动生成的 API 代码示例设置。
自动生成的代码片段的语言。有关可用语言和别名的完整列表，请参阅支持的语言。 是否使用 OpenAPI 规范中的示例值预填充演练场。默认为 false。
是否根据 API 规范为端点生成代码示例。默认为 true。当设置为 false 时，演练场中仅显示手动编写的代码示例（来自 OpenAPI 中的 x-codeSamples 或 MDX 中的 <RequestExample> 组件）。
OpenAPI 规范显示设置。包括 API 参考页面上的下载按钮。
是否在 API 参考页面上显示 OpenAPI 规范的下载按钮。默认为 false。
从 MDX 文件而非 OpenAPI 规范构建的 API 页面的设置。
基于 MDX 的 API 请求的身份验证配置。
method
"bearer" | "basic" | "key" | "cobo"
API 请求的身份验证方法。
添加到页面级 api frontmatter 字段中相对路径前面的基础 URL。当 frontmatter 包含完整 URL 时不使用此设置。
{
"api": {
"openapi": ["openapi/v1.json", "openapi/v2.json"],
"playground": {
"display": "interactive"
},
"params": {
"expanded": "all"
},
"url": "full",
"examples": {
"languages": ["curl", "python", "javascript", "go"],
"defaults": "required",
"prefill": true,
"autogenerate": true
},
"spec": {
"download": true
}
}
}
