mintlify__docs/zh/organize/settings-api.mdx

---
title: "API 设置"
description: "在 docs.json 文件中配置 OpenAPI 和 AsyncAPI 规范、交互式 API 演练场、SDK 代码示例和身份验证设置。"
keywords: ["api", "openapi", "asyncapi", "演练场", "docs.json", "api 参考"]
---

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

## 设置

### `api`

**类型：** `object`

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

<ResponseField name="api.openapi" type="string 或 array 或 object">
  用于生成 API 参考页面的 OpenAPI 规范文件。接受单个路径或 URL、路径和 URL 数组，或指定 source 和 directory 的对象。

  <Expandable title="api.openapi object">
    <ResponseField name="source" type="string">
      你的 OpenAPI 规范文件的 URL 或路径。最小长度：1。
    </ResponseField>
    <ResponseField name="directory" type="string">
      搜索 OpenAPI 文件的目录。开头不要包含斜杠。
    </ResponseField>
  </Expandable>

  <CodeGroup>

  ```json 单个文件
  "openapi": "openapi.json"
  ```

  ```json 多个文件
  "openapi": [
    "openapi/v1.json",
    "openapi/v2.json",
    "https://api.example.com/openapi.yaml"
  ]
  ```

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

  </CodeGroup>
</ResponseField>

<ResponseField name="api.asyncapi" type="string 或 array 或 object">
  用于生成事件驱动 API 参考页面的 AsyncAPI 规范文件。接受单个路径或 URL、路径和 URL 数组，或指定 source 和 directory 的对象。

  <Expandable title="api.asyncapi object">
    <ResponseField name="source" type="string">
      你的 AsyncAPI 规范文件的 URL 或路径。最小长度：1。
    </ResponseField>
    <ResponseField name="directory" type="string">
      搜索 AsyncAPI 文件的目录。开头不要包含斜杠。
    </ResponseField>
  </Expandable>

  <CodeGroup>

  ```json 单个文件
  "asyncapi": "asyncapi.json"
  ```

  ```json 多个文件
  "asyncapi": [
    "asyncapi/events.yaml",
    "asyncapi/webhooks.yaml"
  ]
  ```

  ```json 目录
  "asyncapi": {
    "source": "asyncapi.json",
    "directory": "websockets"
  }
  ```

  </CodeGroup>
</ResponseField>

<ResponseField name="api.playground" type="object">
  交互式 API 演练场设置。

  <Expandable title="api.playground">
    <ResponseField name="display" type='"interactive" | "simple" | "none" | "auth"'>
      演练场的显示模式。默认为 `interactive`。

      - `interactive` — 完整的交互式演练场，带请求构建器
      - `simple` — 简化视图，不带请求构建器
      - `none` — 完全隐藏演练场
      - `auth` — 仅向已认证用户显示演练场
    </ResponseField>
    <ResponseField name="proxy" type="boolean">
      是否通过代理服务器路由 API 请求。默认为 `true`。
    </ResponseField>
    <ResponseField name="credentials" type="boolean">
      当 `proxy` 为 `false` 时，是否在跨域请求中包含 cookies 和身份验证头。默认为 `false`。当 `proxy` 为 `true` 时无效。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="api.params" type="object">
  API 参数的显示设置。

  <Expandable title="api.params">
    <ResponseField name="expanded" type='"all" | "closed"'>
      是否默认展开所有参数。默认为 `closed`。
    </ResponseField>
    <ResponseField name="post" type="string 数组">
      要在 API 参考页面和 playground 中每个参数名称旁显示为 post 标签的 OpenAPI 规范字段键名。对于你列出的每个键，Mintlify 都会从 schema 中读取对应的值并将其渲染为标签：

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

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

<ResponseField name="api.url" type='"full"'>
  端点标题中基础 URL 的显示模式。设置为 `full` 可始终在每个端点页面显示完整的基础 URL。默认情况下，仅当有多个基础 URL 可选择时才显示基础 URL。
</ResponseField>

<ResponseField name="api.examples" type="object">
  自动生成的 API 代码示例设置。

  <Expandable title="api.examples">
    <ResponseField name="languages" type="string 数组">
      自动生成的代码片段的语言。有关可用语言和别名的完整列表，请参阅[支持的语言](/zh/api-playground/overview#all-supported-languages)。
    </ResponseField>
    <ResponseField name="defaults" type='"required" | "all"'>
      是否在生成的示例中包含可选参数。默认为 `all`。
    </ResponseField>
    <ResponseField name="prefill" type="boolean">
      是否使用 OpenAPI 规范中的示例值预填充演练场。默认为 `false`。
    </ResponseField>
    <ResponseField name="autogenerate" type="boolean">
      是否根据 API 规范为端点生成代码示例。默认为 `true`。当设置为 `false` 时，演练场中仅显示手动编写的代码示例（来自 OpenAPI 中的 `x-codeSamples` 或 MDX 中的 `<RequestExample>` 组件）。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="api.mdx" type="object">
  从 MDX 文件而非 OpenAPI 规范构建的 API 页面的设置。

  <Expandable title="api.mdx">
    <ResponseField name="auth" type="object">
      基于 MDX 的 API 请求的身份验证配置。

      <Expandable title="auth">
        <ResponseField name="method" type='"bearer" | "basic" | "key" | "cobo"'>
          API 请求的身份验证方法。
        </ResponseField>
        <ResponseField name="name" type="string">
          API 请求的身份验证参数名称。
        </ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="server" type="string 或 array">
      添加到页面级 `api` frontmatter 字段中相对路径前面的基础 URL。当 frontmatter 包含完整 URL 时不使用此设置。
    </ResponseField>
  </Expandable>
</ResponseField>

## 示例

```json 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
    }
  }
}
```