手动创建 API 文档页面
当你需要完全控制布局时，使用 MDX 文件手动创建 API 参考页面，适用于小型 API、原型开发或自定义文档。
你可以在独立的 MDX 页面中手动定义各个 API 端点。这种方式适用于小型 API 或原型开发阶段。
配置 API 参数
在你的 docs.json 文件中配置基础 URL 和认证方式。
"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'- 显示可复制的端点，不带 Playgroundplayground: '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 字段，将你的接口端点页面添加到导航中：
"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 文件路径和端点来引用特定端点：
"navigation": {
"pages": [
"introduction",
"/path/to/users-openapi.json POST /users",
"/path/to/orders-openapi.json GET /orders"
]
}你也可以为某个导航分组设置默认的 OpenAPI 规范，并通过方法和路径引用端点：
{
"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 字段为单个页面进行重写。页面级设置将覆盖全局设置。
"api": {
"mdx": {
"auth": {
"method": "bearer"
}
}
}"api": {
"mdx": {
"auth": {
"method": "basic"
}
}
}"api": {
"mdx": {
"auth": {
"method": "key",
"name": "x-api-key"
}
}
}要在特定页面禁用身份验证，请将 authMethod 设置为 none：
---
title: "您的页面标题"
authMethod: "none"
---