手动创建 API 文档页面

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

配置

配置 API 参数

在你的 docs.json 文件中配置基础 URL 和认证方式。

Example docs.json

"api": {
  "mdx": {
    "server": "https://api.acme.com/",
    "auth": {
      "method": "key",
      "name": "x-api-key"
    }
  }
}

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

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

你可以在 Settings 中查看完整的 API 配置列表。

创建接口页面

为每个端点创建一个 MDX 文件。在 frontmatter 中定义 title 和 api：

---
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 会被添加到该路径前面。

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

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

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

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

Options:

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

添加参数与响应

使用参数和响应字段为端点的参数和返回值编写文档。

<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>

在文档中添加 API 端点

通过更新 docs.json 中的 pages 字段，将你的接口端点页面添加到导航中：

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。在导航中了解如何组织你的文档结构。

在导航中使用 OpenAPI 端点

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

docs.json

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

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

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 设置。

启用身份验证

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

Bearer 令牌

"api": {
  "mdx": {
    "auth": {
      "method": "bearer"
    }
  }
}

---
title: "页面标题"
authMethod: "bearer"
---

基本身份验证

"api": {
  "mdx": {
    "auth": {
      "method": "basic"
    }
  }
}

---
title: "页面标题"
authMethod: "basic"
---

API 密钥

"api": {
  "mdx": {
    "auth": {
      "method": "key",
      "name": "x-api-key"
    }
  }
}

---
title: "页面标题"
authMethod: "key"
---

无

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

Page Metadata

---
title: "您的页面标题"
authMethod: "none"
---

​配置

​在导航中使用 OpenAPI 端点

​启用身份验证

​Bearer 令牌

​基本身份验证

​API 密钥

​无

配置

在导航中使用 OpenAPI 端点

启用身份验证

Bearer 令牌

基本身份验证

API 密钥

无