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

​
配置

1

配置 API 参数

在你的 docs.json 文件中配置基础 URL 和认证方式。
"api": {
  "mdx": {
    "server": "https://mintlify.com/api",
    "auth": {
      "method": "key",
      "name": "x-api-key"
    }
  }
}
如果你想隐藏 API 操作台，将 display 字段设置为 none。在隐藏 API 操作台的情况下，你无需配置任何认证方式。
"api": {
  "playground": {
    "display": "none"
  }
}
你可以在 Settings 中查看完整的 API 配置列表。
2

创建接口页面

为每个端点创建一个 MDX 文件。在 frontmatter 中定义 title 和 api：
---
title: '创建新用户'
api: 'POST https://api.mintlify.com/user'
---
将路径参数用 {} 括起来即可指定：
https://api.example.com/v1/endpoint/{userId}
如果你在 docs.json 中配置了 server 字段，就可以使用例如 /v1/endpoint 这样的相对路径。
要在特定页面上覆盖全局的 playground 显示模式，请在 frontmatter 中添加 playground：
---
title: '创建新用户'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
Options:
  • playground: 'interactive' - 显示交互式 Playground（默认）
  • playground: 'simple' - 显示可复制的端点，不带 Playground
  • playground: 'none' - 完全隐藏 Playground
3

添加参数与响应

使用参数和响应字段为端点的参数和返回值编写文档。
<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>
4

在文档中添加 API 端点

通过更新 docs.json 中的 pages 字段，将你的接口端点页面添加到导航中：
docs.json
"navigation": {
  "tabs": [
    {
      "tab": "API 参考",
      "groups": [
        {
          "group": "用户",
          "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": [
    "概述",
    "认证",
    "GET /users",
    "POST /users",
    {
      "group": "订单",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}
有关 OpenAPI 集成的更多信息，请参见 OpenAPI 设置。

​
启用身份验证

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

​
Bearer 令牌

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

​
基本身份验证

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

​
API 密钥

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

​
无

要在特定页面禁用身份验证，请将 authMethod 设置为 none：
Page Metadata
---
title: "您的页面标题"
authMethod: "none"
---