API 设置

使用 docs.json 中的 api 字段来配置哪些 API 规范生成 API 页面、用于测试端点的交互式 API 演练场，以及如何生成和显示代码示例。

设置

`api`

类型： object 在 api 键下定义所有与 API 相关的设置。

string 或 array 或 object

用于生成 API 参考页面的 OpenAPI 规范文件。接受单个路径或 URL、由路径、URL 和对象组成的数组，或指定 source、directory 和 overlays 的对象。

显示 api.openapi object

string

你的 OpenAPI 规范文件的 URL 或路径。最小长度：1。

string

搜索 OpenAPI 文件的目录。开头不要包含斜杠。

string 数组

要按顺序应用到该规范的 OpenAPI Overlay 文档的路径或 URL。空数组会禁用该规范的所有 Overlay，包括自动发现的 Overlay。

"openapi": "openapi.json"

"openapi": [
  "openapi/v1.json",
  "openapi/v2.json",
  "https://api.example.com/openapi.yaml"
]

"openapi": {
  "source": "openapi.json",
  "directory": "api-reference"
}

"openapi": {
  "source": "openapi.json",
  "overlays": ["overlays/docs-adjustments.yaml"]
}

string 或 array 或 object

用于生成事件驱动 API 参考页面的 AsyncAPI 规范文件。接受单个路径或 URL、路径和 URL 数组，或指定 source 和 directory 的对象。

显示 api.asyncapi object

string

你的 AsyncAPI 规范文件的 URL 或路径。最小长度：1。

string

搜索 AsyncAPI 文件的目录。开头不要包含斜杠。

"asyncapi": "asyncapi.json"

"asyncapi": [
  "asyncapi/events.yaml",
  "asyncapi/webhooks.yaml"
]

"asyncapi": {
  "source": "asyncapi.json",
  "directory": "websockets"
}

object

交互式 API 演练场设置。

显示 api.playground

"interactive" | "simple" | "none" | "auth"

演练场的显示模式。默认为 interactive。

interactive: 完整的交互式演练场，带请求构建器
simple: 简化视图，不带请求构建器
none: 完全隐藏演练场
auth: 仅向已认证用户显示演练场

boolean

是否通过代理服务器路由 API 请求。默认为 true。

boolean

当 proxy 为 false 时，是否在跨域请求中包含 cookies 和身份验证头。默认为 false。当 proxy 为 true 时无效。

object

API 参数的显示设置。

显示 api.params

"all" | "closed"

是否默认展开所有参数。默认为 closed。

string 数组

要在 API 参考页面和 playground 中每个参数名称旁显示为 post 标签的 OpenAPI 规范字段键名。对于你列出的每个键，Mintlify 都会从 schema 中读取对应的值并将其渲染为标签：

字符串值会按字面渲染。
true 会将键名作为标签内容渲染。false、null 和空字符串不会渲染任何内容。
数字值会渲染为字符串化的数字。
字符串或数字数组会为每个元素渲染一个标签。
对象和其他值会被忽略。

使用此设置可将自定义 OpenAPI 字段（例如 x-internal、nullable 或厂商扩展）作为可视化注释显示在每个参数上，而无需逐个属性进行配置。

"collapsed" | "expanded" | "static"

API playground 中可选请求字段的显示方式。必填字段始终显示在最前面。默认为 collapsed。

collapsed：在每个部分中将可选字段隐藏在展开控件后面。
expanded：默认显示可选字段。读者仍可将其折叠。
static：始终在必填字段之后显示可选字段，不提供展开或折叠控件。

"full"

端点标题中基础 URL 的显示模式。设置为 full 可始终在每个端点页面显示完整的基础 URL。默认情况下，仅当有多个基础 URL 可选择时才显示基础 URL。

object

自动生成的 API 代码示例设置。

显示 api.examples

string 数组

自动生成的代码片段的语言。有关可用语言和别名的完整列表，请参阅支持的语言。

"required" | "all"

是否在生成的示例中包含可选参数。默认为 all。

boolean

是否使用 OpenAPI 规范中的示例值预填充演练场。默认为 false。

boolean

是否根据 API 规范为端点生成代码示例。默认为 true。当设置为 false 时，演练场中仅显示手动编写的代码示例（来自 OpenAPI 中的 x-codeSamples 或 MDX 中的 <RequestExample> 组件）。

object

从 MDX 文件而非 OpenAPI 规范构建的 API 页面的设置。

显示 api.mdx

object

基于 MDX 的 API 请求的身份验证配置。

显示 auth

"bearer" | "basic" | "key" | "cobo"

API 请求的身份验证方法。

string

API 请求的身份验证参数名称。

string 或 array

添加到页面级 api frontmatter 字段中相对路径前面的基础 URL。当 frontmatter 包含完整 URL 时不使用此设置。

示例

docs.json

{
  "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
    }
  }
}

快速入门

创建内容

管理站点

Agent

Assistant

面向 Agent 的内容

搜索与 SEO

编写 API 文档

集成

参考

设置

`api`

示例

​设置

​api

​示例

设置

`api`

示例