API 设置

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

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

​

设置

​

api

类型： object

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

api.openapi · string or array or object

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

显示 api.openapi object

source · string

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

directory · string

搜索 OpenAPI 文件的目录。不要包含前导斜杠。

Single file

"openapi": "openapi.json"

api.asyncapi · string or array or object

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

显示 api.asyncapi object

source · string

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

directory · string

搜索 AsyncAPI 文件的目录。不要包含前导斜杠。

Single file

"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 · array of string

自动生成代码片段的语言。查看 支持的语言 获取完整的可用语言和别名列表。

defaults · "required" | "all"

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

prefill · boolean

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

autogenerate · boolean

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

api.spec · object

OpenAPI 规范显示设置。包括 API 参考页面上的下载按钮。

显示 api.spec

download · boolean

是否在 API 参考页面上显示 OpenAPI 规范的下载按钮。默认为 false。

api.mdx · object

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

显示 api.mdx

auth · object

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

显示 auth

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

API 请求的身份验证方法。

name · string

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

server · string or 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
    },
    "spec": {
      "download": true
    }
  }
}