# 手动创建 API 文档页面 (/zh/api-playground/mdx-setup)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 1593 · updated: 2026-07-30 -->
Related: [操作台](/zh/api-playground/overview.md), [OpenAPI 设置](/zh/api-playground/openapi-setup.md), [复杂数据类型](/zh/api-playground/complex-data-types.md), [添加 SDK 示例](/zh/api-playground/adding-sdk-examples.md), [管理页面可见性](/zh/api-playground/managing-page-visibility.md), [多种响应](/zh/api-playground/multiple-responses.md)

你可以在独立的 MDX 页面中手动定义各个 API 端点。这种方式适用于小型 API 或原型开发阶段。

<div id="setup">
  ## 配置 [#配置]
</div>

<Steps>
  <Step title="配置 API 参数">
    在你的 `docs.json` 文件中配置基础 URL 和认证方式。

    ```json title="Example docs.json"
    "api": {
      "mdx": {
        "server": "https://api.acme.com/",
        "auth": {
          "method": "key",
          "name": "x-api-key"
        }
      }
    }
    ```

    如果你想隐藏 API 操作台，将 `display` 字段设置为 `none`。在隐藏 API 操作台的情况下，你无需配置任何认证方式。

    ```json
    "api": {
      "playground": {
        "display": "none"
      }
    }
    ```

    你可以在 [Settings](/zh/organize/settings-api) 中查看完整的 API 配置列表。
  </Step>

  <Step title="创建接口页面">
    为每个端点创建一个 MDX 文件。在 frontmatter 中定义 `title` 和 `api`：

    ```mdx
    ---
    title: '创建新用户'
    api: 'POST /v1/users'
    ---
    ```

    `api` frontmatter 字段可以是完整 URL 或相对路径：

    * **完整 URL**，例如 `POST https://api.acme.com/v1/users`。对于该端点，会忽略 `docs.json` 中的 `server` 字段。
    * **相对路径**，例如 `POST /v1/users`。需要在 `docs.json` 中配置 `server` 字段。服务器 URL 会被添加到该路径前面。

    将路径参数用 `{}` 括起来即可指定：

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

    要在特定页面上覆盖全局的 playground 显示模式，请在 frontmatter 中添加 `playground`：

    ```mdx
    ---
    title: '创建新用户'
    api: 'POST https://api.mintlify.com/user'
    playground: 'none'
    ---
    ```

    Options:

    * `playground: 'interactive'` - 显示交互式 Playground（默认）
    * `playground: 'simple'` - 显示可复制的端点，不带 Playground
    * `playground: 'none'` - 完全隐藏 Playground
  </Step>

  <Step title="添加参数与响应">
    使用[参数和响应字段](/zh/components/fields)为端点的参数和返回值编写文档。

    ```mdx
    <ParamField path="userId" type="string" required>
      用户的唯一标识符
    </ParamField>

    <ParamField body="email" type="string" required>
      用户的电子邮件地址
    </ParamField>

    <ResponseField name="id" type="string" required>
      新创建用户的唯一标识符
    </ResponseField>

    <ResponseField name="email" type="string" required>
      用户的电子邮件地址
    </ResponseField>
    ```
  </Step>

  <Step title="在文档中添加 API 端点">
    通过更新 `docs.json` 中的 `pages` 字段，将你的接口端点页面添加到导航中：

    ```json title="docs.json"
    "navigation": {
      "tabs": [
        {
          "tab": "API Reference",
          "groups": [
            {
              "group": "Users",
              "pages": [
                "api-reference/users/create-user",
                "api-reference/users/get-user",
                "api-reference/users/update-user"
              ]
            },
            {
              "group": "订单",
              "pages": [
                "api-reference/orders/create-order",
                "api-reference/orders/list-orders"
              ]
            }
          ]
        }
      ]
    }
    ```

    每个页面路径都对应于 docs 存储库中的一个 MDX 文件。例如，`api-reference/users/create-user.mdx`。在[导航](/zh/organize/navigation)中了解如何组织你的文档结构。

    ### 在导航中使用 OpenAPI 端点 [#在导航中使用-openapi-端点]

    如果你有 OpenAPI 规范文件，你可以在导航中直接引用端点，而无需创建单独的 MDX 文件。通过包含 OpenAPI 文件路径和端点来引用特定端点：

    ```json title="docs.json"
    "navigation": {
      "pages": [
        "introduction",
        "/path/to/users-openapi.json POST /users",
        "/path/to/orders-openapi.json GET /orders"
      ]
    }
    ```

    你也可以为某个导航分组设置默认的 OpenAPI 规范，并通过方法和路径引用端点：

    ```json title="docs.json"
    {
      "group": "API 参考",
      "openapi": "/path/to/openapi-v1.json",
      "pages": [
        "overview",
        "authentication",
        "GET /users",
        "POST /users",
        {
          "group": "Orders",
          "openapi": "/path/to/openapi-v2.json",
          "pages": [
            "GET /orders",
            "POST /orders"
          ]
        }
      ]
    }
    ```

    有关 OpenAPI 集成的更多信息，请参见 [OpenAPI 设置](/zh/api-playground/openapi-setup)。
  </Step>
</Steps>

<div id="enable-authentication">
  ## 启用身份验证 [#启用身份验证]
</div>

你可以在 `docs.json` 中设置全局身份验证，或在页面的 frontmatter 中通过 `authMethod` 字段为单个页面进行重写。页面级设置将覆盖全局设置。

<div id="bearer-token">
  ### Bearer 令牌 [#bearer-令牌]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="docs.json" groupId="docs-json+page-metadata">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="docs.json">
        docs.json
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Page Metadata">
        Page Metadata
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="docs.json">
      ```json  
      "api": {
        "mdx": {
          "auth": {
            "method": "bearer"
          }
        }
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Page Metadata">
      ```mdx  
      ---
      title: "页面标题"
      authMethod: "bearer"
      ---
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="basic-authentication">
  ### 基本身份验证 [#基本身份验证]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="docs.json" groupId="docs-json+page-metadata">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="docs.json">
        docs.json
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Page Metadata">
        Page Metadata
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="docs.json">
      ```json  
      "api": {
        "mdx": {
          "auth": {
            "method": "basic"
          }
        }
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Page Metadata">
      ```mdx  
      ---
      title: "页面标题"
      authMethod: "basic"
      ---
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="api-key">
  ### API 密钥 [#api-密钥]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="docs.json" groupId="docs-json+page-metadata">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="docs.json">
        docs.json
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Page Metadata">
        Page Metadata
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="docs.json">
      ```json  
      "api": {
        "mdx": {
          "auth": {
            "method": "key",
            "name": "x-api-key"
          }
        }
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Page Metadata">
      ```mdx  
      ---
      title: "页面标题"
      authMethod: "key"
      ---
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

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

要在特定页面禁用身份验证，请将 `authMethod` 设置为 `none`：

```mdx title="Page Metadata"
---
title: "您的页面标题"
authMethod: "none"
---
```