Mintlify AI 自动化文档生成工具实操指南

核心操作逻辑

使用 Skill 相当于给 AI 提供了'标准答案'，AI 会严格按照定义的规范、模板生成文档，格式规范且无需手动修改。

具体操作步骤（以 Cursor 为例）

1. 打开 Cursor 编辑器，新建空白 MDX 文件。
2. 输入命令：/mintlify，按下空格，输入自然语言描述。

   例如：/mintlify 生成 Mintlify Accordions 组件的使用文档，包含组件介绍、参数说明、示例代码、注意事项

3. 按下回车，AI 自动生成符合规范的文档，包含 mdx 格式文档文件和 docs.json 配置文件。

自定义修改 Skill 提示词

熟悉规范后，可手动修改 Skill 提示词。以 Cursor 为例，保存目录为 .cursor/skills/mintlify，找到 skill.md 文件进行修改。注意不要破坏原有规范结构。

实操步骤三：启动 Mintlify，预览和查看文档

生成文档内容后，需启动 Mintlify 服务进行预览。

启动 Mintlify 服务

1. 打开终端，进入存放文档文件的目录。
2. 输入命令：

npx mintlify dev

当终端输出'Local development server running at: http://localhost:3000'时，服务启动成功。

预览和查看文档

1. 浏览器访问 http://localhost:3000。
2. 在导航栏中找到生成的文档，点击查看。
3. 修改文档内容后，浏览器会自动刷新，无需重新启动服务。

进阶实操：基于 openapi.json 生成 OpenAPI 接口文档

Mintlify 支持基于 openapi.json 文件，一键生成专业的 OpenAPI 接口文档。

前提：获取 openapi.json 文件

主流 Web 开发框架（如 Spring Boot、FastAPI）都支持自动生成 openapi.json 文件。

FastAPI 框架

FastAPI 原生支持 OpenAPI 规范。启动应用后，访问 http://localhost:8000/openapi.json 即可获取文件。

示例代码：

from fastapi import FastAPI
app = FastAPI(openapi_url="/openapi.json")

Spring Boot 框架

需添加 springdoc-openapi 依赖。在 application.yml 中配置访问路径，启动后访问对应地址获取 JSON 文件。

将 openapi.json 关联到 Mintlify 文档

1. 将 openapi.json 文件放到 Mintlify 文档目录根路径下。
2. 新建 MDX 文件（如 openapi-docs.mdx），添加以下代码引入 OpenAPI 组件：

import { OpenAPI } from "@mintlify/components";
<OpenAPI specUrl="/openapi.json" />

3. 保存文件，重新启动 Mintlify 服务（npx mintlify dev）。
4. 浏览器访问并查看生成的接口文档。

生成的 OpenAPI 接口文档具备美观简洁、可交互（支持测试）、结构清晰、信息完整及自动更新等特点。

高级功能初探

Mintlify 还支持以下高级操作：

1. 页面语义检索：支持用户通过自然语言搜索文档内容。
2. 基于 MCP 的查询：通过模型上下文协议连接文档和 API 接口。
3. 基于 GitHub/GitLab 的关联发布：实现文档的自动发布和 PR 预览。
4. 多语言支持与自动翻译：快速将文档翻译成多种语言。
5. 文档数据分析：统计访问量、搜索关键词等信息。

总结

Mintlify 作为一款 AI 原生的文档自动化工具，以其简约的风格、便捷的操作、强大的功能，成为开发者的得力助手。通过本文的实操教程，可以快速掌握 Mintlify 的核心用法，包括环境搭建、Skill 安装、文档生成、预览及接口文档生成，大幅提升技术文档编写和维护的效率。