API 设置

在 docs.json 中配置 OpenAPI 和 AsyncAPI 规范、交互式演练场、代码示例和身份验证。

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

​

设置

​

api

类型： object

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

api.openapi · string 或 array 或 object

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

显示 api.openapi object

source · string

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

directory · string

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

单个文件

"openapi": "openapi.json"

api.asyncapi · string 或 array 或 object

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

显示 api.asyncapi object

source · string

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

directory · string

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

单个文件

"asyncapi": "asyncapi.json"

api.playground · object

交互式 API 演练场设置。

显示 api.playground

display · "interactive" | "simple" | "none" | "auth"

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

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

proxy · boolean

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

api.params · object

API 参数的显示设置。

显示 api.params

expanded · "all" | "closed"

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

api.url · "full"

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

api.examples · object

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

显示 api.examples

languages · string 数组

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

defaults · "required" | "all"

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

prefill · boolean

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

autogenerate · boolean

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

api.mdx · object

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

显示 api.mdx

auth · object

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

显示 auth

method · "bearer" | "basic" | "key" | "cobo"

API 请求的身份验证方法。

name · string

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

server · string 或 array

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

​

示例

docs.json

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