> ## Documentation Index
> Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MDX 设置

> 使用 `MDX` 为你的 API 端点生成文档页面

你可以在单独的 `MDX` 文件中手动定义 API 端点，而不是使用 OpenAPI 规范。此方法为自定义内容提供灵活性，但对于大多数项目，我们建议从 OpenAPI 规范文件生成 API 文档，因为这样更易维护且功能更完善。不过，为 API 创建 `MDX` 页面在记录小型 API 或用于原型设计时依然非常实用。

要使用 `MDX` 为 API 端点生成页面，请在 `docs.json` 中配置 API 设置，为每个端点创建对应的 `MDX` 文件，并使用 `<ParamFields />` 等组件定义参数。基于这些定义，Mintlify 会生成交互式 API 操作台、请求示例和响应示例。

<Steps>
  <Step title="配置 API">
    在 `docs.json` 文件中定义基础 URL 和认证方式：

    ```json theme={null}
     "api": {
      "mdx": {
        "server": "https://mintlify.com/api", // string array for multiple base URLs
        "auth": {
          "method": "key",
          "name": "x-api-key" // options: bearer, basic, key.
        }
      }
    }
    ```

    如果想隐藏 API 操作台，请使用 `display` 字段。隐藏操作台时，无需配置认证方式。

    ```json theme={null}
    "api": {
      "playground": {
        "display": "none"
      }
    }
    ```

    在[设置](/zh/settings#api-configurations)中查看完整的 API 配置列表。
  </Step>

  <Step title="创建端点页面">
    每个 API 端点页面都应有一个对应的 `MDX` 文件。在每个文件顶部定义 `title` 和 `api`：

    ```mdx theme={null}
    ---
    title: 'Create new user'
    api: 'POST https://api.mintlify.com/user'
    ---
    ```

    你可以通过将参数名添加到路径中并用 `{}` 包裹来指定路径参数：

    ```bash theme={null}
    https://api.example.com/v1/endpoint/{userId}
    ```

    <Note>
      如果在 `docs.json` 中配置了 `server` 字段，你可以使用相对路径，例如 `/v1/endpoint`。
    </Note>

    你可以在 frontmatter 中添加 `playground`，以覆盖全局的 API 操作台展示模式：

    ```mdx theme={null}
    ---
    title: 'Create new user'
    api: 'POST https://api.mintlify.com/user'
    playground: 'none'
    ---
    ```

    * `playground: 'interactive'` - 显示交互式操作台。
    * `playground: 'simple'` - 显示可复制的端点，无操作台。
    * `playground: 'none'` - 隐藏操作台。
  </Step>

  <Step title="将端点添加到文档">
    将端点页面的路径添加到 `docs.json` 的 `navigation` 字段，即可将其加入侧边栏。关于文档结构的更多信息，参见[导航](/zh/navigation)。
  </Step>
</Steps>

<div id="enabling-authentication">
  ## 启用认证
</div>

你可以在 `docs.json` 中添加一种认证方式，将其全局应用到每个页面，也可以按页面单独设置。

如果同时设置了全局方式和页面方式，页面的认证方式会覆盖全局方式。

<div id="bearer-token">
  ### Bearer token
</div>

<CodeGroup>
  ```json docs.json theme={null}
  "api": {
      "mdx": {
        "auth": {
          "method": "bearer"
        }
      }
  }
  ```

  ```mdx Page Metadata theme={null}
  ---
  title: "Your page title"
  authMethod: "bearer"
  ---
  ```
</CodeGroup>

<div id="basic-authentication">
  ### 基本认证
</div>

<CodeGroup>
  ```json docs.json theme={null}
  "api": {
      "mdx": {
        "auth": {
          "method": "basic"
        }
      }
  }
  ```

  ```mdx Page Metadata theme={null}
  ---
  title: "Your page title"
  authMethod: "basic"
  ---
  ```
</CodeGroup>

<div id="api-key">
  ### API key
</div>

<CodeGroup>
  ```json docs.json theme={null}
  "api": {
      "mdx": {
        "auth": {
          "method": "key",
          "name": "x-api-key"
        }
      }
  }
  ```

  ```mdx Page Metadata theme={null}
  ---
  title: "Your page title"
  authMethod: "key"
  ---
  ```
</CodeGroup>

<div id="none">
  ### 无
</div>

在 docs.json 中设置默认值后，可以使用 `none` 认证方式在特定端点上禁用认证。

<CodeGroup>
  ```mdx Page Metadata theme={null}
  ---
  title: "Your page title"
  authMethod: "none"
  ---
  ```
</CodeGroup>