API 设置
在 docs.json 文件中配置 OpenAPI 和 AsyncAPI 规范、交互式 API 演练场、SDK 代码示例和身份验证设置。
使用 docs.json 中的 api 字段来配置哪些 API 规范生成 API 页面、用于测试端点的交互式 API 演练场，以及如何生成和显示代码示例。
设置
api
类型： object
在 api 键下定义所有与 API 相关的设置。
api.openapistring 或 array 或 object用于生成 API 参考页面的 OpenAPI 规范文件。接受单个路径或 URL、路径和 URL 数组，或指定 source 和 directory 的对象。
Show Hide api.openapi object
sourcestring你的 OpenAPI 规范文件的 URL 或路径。最小长度：1。
directorystring搜索 OpenAPI 文件的目录。开头不要包含斜杠。
"openapi": "openapi.json"api.asyncapistring 或 array 或 object用于生成事件驱动 API 参考页面的 AsyncAPI 规范文件。接受单个路径或 URL、路径和 URL 数组，或指定 source 和 directory 的对象。
Show Hide api.asyncapi object
sourcestring你的 AsyncAPI 规范文件的 URL 或路径。最小长度：1。
directorystring搜索 AsyncAPI 文件的目录。开头不要包含斜杠。
"asyncapi": "asyncapi.json"api.playgroundobject交互式 API 演练场设置。
Show Hide api.playground
display"interactive" | "simple" | "none" | "auth"演练场的显示模式。默认为 interactive。
interactive— 完整的交互式演练场，带请求构建器simple— 简化视图，不带请求构建器none— 完全隐藏演练场auth— 仅向已认证用户显示演练场
proxyboolean是否通过代理服务器路由 API 请求。默认为 true。
credentialsboolean当 proxy 为 false 时，是否在跨域请求中包含 cookies 和身份验证头。默认为 false。当 proxy 为 true 时无效。
api.paramsobjectAPI 参数的显示设置。
Show Hide api.params
expanded"all" | "closed"是否默认展开所有参数。默认为 closed。
poststring 数组要在 API 参考页面和 playground 中每个参数名称旁显示为 post 标签的 OpenAPI 规范字段键名。对于你列出的每个键，Mintlify 都会从 schema 中读取对应的值并将其渲染为标签：
- 字符串值会按字面渲染。
true会将键名作为标签内容渲染。false、null和空字符串不会渲染任何内容。- 数字值会渲染为字符串化的数字。
- 字符串或数字数组会为每个元素渲染一个标签。
- 对象和其他值会被忽略。
使用此设置可将自定义 OpenAPI 字段（例如 x-internal、nullable 或厂商扩展）作为可视化注释显示在每个参数上，而无需逐个属性进行配置。
api.url"full"端点标题中基础 URL 的显示模式。设置为 full 可始终在每个端点页面显示完整的基础 URL。默认情况下，仅当有多个基础 URL 可选择时才显示基础 URL。
api.examplesobject自动生成的 API 代码示例设置。
Show Hide api.examples
languagesstring 数组自动生成的代码片段的语言。有关可用语言和别名的完整列表，请参阅支持的语言。
defaults"required" | "all"是否在生成的示例中包含可选参数。默认为 all。
prefillboolean是否使用 OpenAPI 规范中的示例值预填充演练场。默认为 false。
autogenerateboolean是否根据 API 规范为端点生成代码示例。默认为 true。当设置为 false 时，演练场中仅显示手动编写的代码示例（来自 OpenAPI 中的 x-codeSamples 或 MDX 中的 <RequestExample> 组件）。
api.mdxobject从 MDX 文件而非 OpenAPI 规范构建的 API 页面的设置。
Show Hide api.mdx
authobject基于 MDX 的 API 请求的身份验证配置。
Show Hide auth
method"bearer" | "basic" | "key" | "cobo"API 请求的身份验证方法。
namestringAPI 请求的身份验证参数名称。
serverstring 或 array添加到页面级 api frontmatter 字段中相对路径前面的基础 URL。当 frontmatter 包含完整 URL 时不使用此设置。
示例
{
"api": {
"openapi": ["openapi/v1.json", "openapi/v2.json"],
"playground": {
"display": "interactive"
},
"params": {
"expanded": "all",
"post": ["nullable", "x-internal"]
},
"url": "full",
"examples": {
"languages": ["curl", "python", "javascript", "go"],
"defaults": "required",
"prefill": true,
"autogenerate": true
}
}
}