MDX 设置

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

你可以在单独的 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 token

docs.json

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

​

基本认证

docs.json

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

​

API key

docs.json

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

​

无

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

Page Metadata

---
title: "Your page title"
authMethod: "none"
---