你可以在单独的 MDX 文件中手动定义 API 端点，而不是使用 OpenAPI 规范。此方法为自定义内容提供灵活性，但对于大多数项目，我们建议从 OpenAPI 规范文件生成 API 文档，因为它更易维护且功能更丰富。不过，为 API 创建 MDX 页面在记录小型 API 或用于原型设计时会很有帮助。 要使用 MDX 为 API 端点生成页面，请在 docs.json 中配置 API 设置，为每个端点创建单独的 MDX 文件，并使用 <ParamFields /> 等组件来定义参数。基于这些定义，Mintlify 会生成交互式 API 操作台、请求示例和响应示例。
1

配置你的 API

在 docs.json 文件中定义基础 URL 和认证方式：
 "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 字段。隐藏操作台时无需配置认证方式。
"api": {
  "playground": {
    "display": "none"
  }
}
在设置中查看完整的 API 配置列表。
2

创建端点页面

每个 API 端点页面都应对应一个 MDX 文件。在每个文件的顶部定义 title 和 api：
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
---
你可以通过在路径中添加参数名并用 {} 包裹来指定路径参数：
https://api.example.com/v1/endpoint/{userId}
如果你在 docs.json 中配置了 server 字段，可以使用诸如 /v1/endpoint 的相对路径。
你可以在 frontmatter 中添加 playground 来覆盖当前页面的全局 API 操作台显示模式：
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
  • playground: 'interactive' - 显示交互式操作台。
  • playground: 'simple' - 显示可复制的端点，不包含操作台。
  • playground: 'none' - 隐藏操作台。
3

将端点添加到文档

在 docs.json 的 navigation 字段中添加这些路径，以将端点页面加入侧边栏。在导航中了解更多文档结构相关内容。

​
启用身份验证

你可以在 docs.json 中添加身份验证方法，以在所有页面全局启用；也可以为单个页面单独设置。 如果同时配置了全局方法和页面方法，以页面为准，页面的身份验证方法会覆盖全局方法。

​
Bearer 令牌

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

​
基本身份验证

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

​
API 密钥

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

​
None

在 docs.json 中设置默认身份验证后，可以在特定端点将 none 身份验证方式用于禁用身份验证。 
---
title: "Your page title"
authMethod: "none"
---