AI 自动生成技术文档:接口文档、项目说明与部署手册
一、为什么需要自动生成技术文档?
在软件开发过程中,代码通常会随着功能迭代不断变化,但技术文档却容易被忽略。
例如:
-
新增了 API 接口,却没有及时更新接口说明。
-
修改了数据库字段,项目说明仍然使用旧结构。
-
更换了部署方式,部署手册没有同步更新。
-
项目开发人员发生变化,接手者难以快速理解代码。
这些问题会增加项目维护成本。
AI 可以通过分析源代码、配置文件、数据库模型和项目结构,辅助生成多种技术文档。
常见的文档包括:
| 文档类型 | 主要内容 |
|---|---|
| API 接口文档 | 请求地址、参数、响应格式、认证方式 |
| 项目说明文档 | 项目用途、技术栈、目录结构、模块说明 |
| 数据库设计文档 | 表结构、字段类型、索引、表之间的关系 |
| 部署手册 | 环境准备、安装、配置、启动和更新 |
| 开发规范文档 | 命名规则、代码结构、开发流程 |
| 故障排查文档 | 常见错误、原因分析和解决方法 |
本文以 Python、FastAPI、MySQL 和 Vue 3 项目为例,介绍如何利用 AI 辅助生成、整理和维护技术文档。
需要注意:AI 生成的文档不一定准确。所有接口参数、配置项、命令和部署步骤,都应该以实际项目代码和运行结果为准。
二、让 AI 分析项目并生成说明文档
1. 准备项目结构
假设我们有一个前后端分离项目:
my-project/
├── backend/
│ ├── app/
│ │ ├── main.py
│ │ ├── database.py
│ │ ├── models/
│ │ ├── schemas/
│ │ ├── routers/
│ │ └── services/
│ ├── requirements.txt
│ └── .env.example
│
├── frontend/
│ ├── src/
│ │ ├── api/
│ │ ├── components/
│ │ ├── views/
│ │ └── router/
│ └── package.json
│
├── README.md
└── PROJECT_GUIDE.md
如果是已有项目,不需要为了生成文档而重新调整目录结构。
首先让 AI 阅读项目文件,了解项目的整体情况。
2. 编写项目分析提示词
可以使用下面的提示词:
请分析当前项目,并为项目生成一份技术说明文档。
分析范围:
1. 项目整体目录结构。
2. 后端技术栈和主要依赖。
3. 前端技术栈和主要依赖。
4. 数据库类型和连接方式。
5. 后端 API 路由组织方式。
6. 用户认证和权限控制方式。
7. 前端页面和组件结构。
8. 主要业务模块及其作用。
9. 项目的启动和运行方式。
要求:
- 必须以实际代码为依据。
- 不要根据文件名猜测功能。
- 不要虚构不存在的接口和模块。
- 对无法确认的信息标记为待确认。
- 不要读取或输出 .env 中的真实密钥。
- 不要修改任何业务代码。
请生成 PROJECT_GUIDE.md。
3. 项目说明文档示例
生成的文档可以采用以下结构:
# 项目技术说明
## 1. 项目简介
本项目是一个前后端分离的 Web 应用。
## 2. 技术栈
### 后端
- Python
- FastAPI
- SQLAlchemy
- MySQL
### 前端
- Vue 3
- TypeScript
- Element Plus
- Vite
## 3. 项目目录
- backend:后端代码
- frontend:前端代码
- PROJECT_GUIDE.md:项目说明
## 4. 后端模块
- routers:API 路由
- models:数据库模型
- schemas:数据验证结构
- services:业务逻辑
## 5. 数据库
使用 MySQL 存储业务数据。
## 6. 启动方式
后端和前端分别安装依赖并启动。
## 7. 配置说明
使用环境变量管理数据库连接等配置。
## 8. 注意事项
生产环境应使用独立配置,并保护敏感信息。
这只是文档结构示例。实际生成时,应由 AI 根据项目中的真实模块、接口和启动命令补充内容。
三、使用 FastAPI 自动生成 API 接口文档
FastAPI 本身就提供了 OpenAPI 文档生成能力。
相比完全依靠 AI 阅读代码生成接口说明,直接从 FastAPI 获取 OpenAPI 规范通常更加准确。
AI 可以进一步帮助整理接口说明、补充使用示例和生成 Markdown 文档。
1. 创建 FastAPI 示例项目
安装依赖:
pip install fastapi uvicorn
创建 main.py:
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI(
title="文章管理 API",
description="文章管理系统接口说明",
version="1.0.0"
)
class ArticleCreate(BaseModel):
title: str
content: str
status: str = "draft"
class ArticleResponse(BaseModel):
id: int
title: str
content: str
status: str
@app.get("/")
def index():
return {"message": "API is running"}
@app.get(
"/api/articles",
summary="获取文章列表",
description="分页获取文章列表"
)
def get_articles(page: int = 1, page_size: int = 10):
return {
"page": page,
"page_size": page_size,
"items": []
}
@app.post(
"/api/articles",
response_model=ArticleResponse,
summary="创建文章"
)
def create_article(article: ArticleCreate):
return {
"id": 1,
"title": article.title,
"content": article.content,
"status": article.status
}
启动服务:
uvicorn main:app --reload
2. 查看自动生成的接口文档
启动成功后,打开:
http://127.0.0.1:8000/docs
FastAPI 默认提供 Swagger UI。
<text color="secondary" size="xs">接口文档页面示意</text>
<AsyncImage query="FastAPI Swagger UI OpenAPI interactive API documentation screenshot" aspectRatio="16:9" width="100%" maxHeight={300} fit="contain"/>
还可以访问:
http://127.0.0.1:8000/redoc
查看 ReDoc 格式的接口文档。
<text color="secondary" size="xs">ReDoc 文档页面示意</text>
<AsyncImage query="ReDoc OpenAPI API documentation interface screenshot" aspectRatio="16:9" width="100%" maxHeight={300} fit="contain"/>
3. 导出 OpenAPI JSON
FastAPI 默认提供 OpenAPI JSON 地址:
http://127.0.0.1:8000/openapi.json
可以使用 Python 将其保存到文件:
import json
import urllib.request
url = "http://127.0.0.1:8000/openapi.json"
with urllib.request.urlopen(url) as response:
schema = json.loads(response.read().decode("utf-8"))
with open("openapi.json", "w", encoding="utf-8") as file:
json.dump(
schema,
file,
ensure_ascii=False,
indent=2
)
print("OpenAPI 文档导出完成")
运行:
python export_openapi.py
项目目录中会生成:
openapi.json
这份文件记录了 FastAPI 当前公开的接口规范,包括路径、HTTP 方法、参数、请求体、响应结构和部分说明。
4. 让 AI 根据 OpenAPI 生成 Markdown 接口文档
将 openapi.json 提供给 AI,并使用以下提示词:
请根据我提供的 openapi.json,
生成一份完整的 Markdown API 接口文档。
要求:
1. 列出所有接口。
2. 按业务模块分类。
3. 说明 HTTP 请求方法。
4. 说明接口地址。
5. 说明请求参数和参数类型。
6. 说明必填和选填参数。
7. 说明请求体结构。
8. 说明响应数据结构。
9. 提供 JSON 请求示例。
10. 提供 JSON 响应示例。
11. 说明接口认证要求。
注意:
- 以 OpenAPI 文件为唯一接口依据。
- 不要编造接口地址和参数。
- 无法确定的业务含义标记为待确认。
- 区分实际响应字段和示例字段。
- 输出为 Markdown 格式。
保存为 API_DOCUMENTATION.md。
这样就可以把 FastAPI 的自动接口规范进一步整理为适合开发人员阅读的文档。
重要: 如果项目通过自定义中间件、动态响应或复杂业务逻辑改变了实际响应结构,OpenAPI 文件可能无法完整反映运行行为,需要结合真实接口测试结果进行校验。
四、自动生成数据库设计文档
数据库文档通常需要记录:
-
数据库名称。
-
数据表名称。
-
字段名称。
-
字段类型。
-
是否允许为空。
-
默认值。
-
主键和外键。
-
索引信息。
-
表之间的关联关系。
1. 获取 MySQL 表结构
可以使用 MySQL 命令查看数据库中的表:
SHOW TABLES;
查看指定表结构:
DESCRIBE articles;
查看完整建表语句:
SHOW CREATE TABLE articles;
也可以导出数据库结构,不导出业务数据:
mysqldump -u root -p \
--no-data \
--databases my_database \
> database_schema.sql
执行后会提示输入数据库密码。
注意:导出的 SQL 文件可能包含数据库结构、注释、视图或其他对象定义。分享给 AI 之前,应检查并删除不需要暴露的内部信息。
2. 让 AI 生成数据库说明
将 database_schema.sql 提供给 AI:
请分析这份 MySQL 数据库结构文件,
生成数据库设计说明文档。
要求:
1. 列出所有数据表。
2. 说明每张表的用途。
3. 列出字段名称和字段类型。
4. 说明主键和唯一约束。
5. 说明索引结构。
6. 说明外键关系。
7. 分析表之间的业务关联。
8. 标记可能存在的冗余字段。
9. 指出需要进一步确认的设计问题。
请生成 DATABASE_DESIGN.md。
注意:
- 不要虚构 SQL 中不存在的字段。
- 区分真实外键与根据字段名称推测的业务关联。
- 不要擅自修改数据库结构。
3. 数据库文档示例
例如:
# 数据库设计说明
## articles
文章信息表。
| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT | 主键 |
| title | VARCHAR(255) | 文章标题 |
| content | TEXT | 文章内容 |
| status | VARCHAR(20) | 发布状态 |
| created_at | DATETIME | 创建时间 |
## 索引
- PRIMARY KEY (id)
## 业务说明
用于保存文章的基本信息和正文内容。
数据库设计文档可以帮助新开发人员快速理解数据结构,也能为后续数据库优化提供参考。
五、自动生成 Debian 部署手册
部署文档是项目交付中非常重要的一部分。
一个完整的部署手册,至少应该说明:
-
服务器环境要求。
-
软件依赖。
-
项目目录。
-
环境变量配置。
-
数据库初始化。
-
后端启动方式。
-
前端构建方式。
-
Nginx 配置。
-
HTTPS 配置。
-
服务重启和更新方式。
-
日志查看和故障排查。
-
备份与恢复。
1. 让 AI 分析部署配置
假设项目使用:
-
Debian Linux
-
Python + FastAPI
-
Vue 3 + Vite
-
MySQL
-
Nginx
-
systemd
可以让 AI 分析:
请根据当前项目生成 Debian Linux 部署手册。
分析以下文件:
1. requirements.txt
2. package.json
3. .env.example
4. FastAPI 启动入口
5. Nginx 配置文件
6. systemd 服务配置
7. 数据库初始化脚本
8. 前端构建配置
生成 DEPLOYMENT.md。
文档必须包含:
- 系统环境准备
- 软件安装
- 项目目录规划
- Python 虚拟环境
- 后端依赖安装
- 前端依赖安装
- 环境变量配置
- 数据库初始化
- 前端生产构建
- FastAPI 服务配置
- Nginx 反向代理
- HTTPS 配置说明
- 服务启动和停止
- 日志查看
- 项目更新
- 数据备份与恢复
- 常见故障排查
要求:
- 命令必须与项目实际结构一致。
- 不要虚构服务名称、端口和路径。
- 不要输出真实密钥。
- 对可能影响现有服务的命令进行风险提示。
- 无法确认的配置标记为待确认。
- 不要直接修改服务器配置。
2. systemd 服务说明示例
如果项目确实使用 systemd 管理 FastAPI,可以在部署手册中记录:
sudo systemctl start myapp
sudo systemctl stop myapp
sudo systemctl restart myapp
sudo systemctl status myapp
查看日志:
sudo journalctl -u myapp -n 100 --no-pager
实时查看日志:
sudo journalctl -u myapp -f
这里的 myapp 只是示例服务名称,实际使用时必须以服务器上的服务配置为准。
3. Nginx 配置文档示例
如果项目使用 Nginx 反向代理,可以记录类似配置:
server {
listen 80;
server_name example.com;
location / {
root /var/www/myapp;
try_files $uri $uri/ /index.html;
}
location /api/ {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
这只是一个基础示例。正式部署时还需要根据实际域名、HTTPS、静态文件目录和 API 路由进行调整。
AI 应当根据项目真实配置生成部署说明,而不是直接套用示例配置。
六、建立统一的技术文档目录
当项目规模逐渐增大时,不建议把所有文档都写进 README.md。
可以按照文档用途进行分类。
推荐目录:
my-project/
├── backend/
├── frontend/
├── docs/
│ ├── PROJECT_GUIDE.md
│ ├── API_DOCUMENTATION.md
│ ├── DATABASE_DESIGN.md
│ ├── DEPLOYMENT.md
│ ├── DEVELOPMENT.md
│ ├── TROUBLESHOOTING.md
│ └── CHANGELOG.md
│
├── README.md
└── PROJECT_GUIDE.md
其中:
| 文件 | 主要用途 |
|---|---|
| README.md | 项目简介、快速开始 |
| PROJECT_GUIDE.md | 项目架构与模块说明 |
| API_DOCUMENTATION.md | 接口文档 |
| DATABASE_DESIGN.md | 数据库设计 |
| DEPLOYMENT.md | 部署操作说明 |
| DEVELOPMENT.md | 开发规范 |
| TROUBLESHOOTING.md | 故障排查 |
| CHANGELOG.md | 版本更新记录 |
根目录的 PROJECT_GUIDE.md 可以作为 Agent 的项目上下文入口,而 docs/PROJECT_GUIDE.md 可以保存面向开发人员的详细架构说明。实际项目也可以只保留其中一份,避免重复维护。
七、让 AI 随项目更新自动维护文档
文档生成只是第一步,更重要的是代码发生变化后,文档也要同步更新。
例如:
-
新增一个 API,就更新接口文档。
-
修改数据库字段,就更新数据库设计。
-
新增环境变量,就更新配置说明。
-
修改部署流程,就更新部署手册。
-
修复常见问题,就补充故障排查文档。
可以将以下规则加入项目开发说明:
# 技术文档维护规则
每次开发任务完成后,检查是否需要更新技术文档。
具体要求:
1. 新增或修改 API 时,更新 API_DOCUMENTATION.md。
2. 修改数据库模型时,更新 DATABASE_DESIGN.md。
3. 修改项目结构时,更新 PROJECT_GUIDE.md。
4. 修改部署配置时,更新 DEPLOYMENT.md。
5. 新增环境变量时,更新配置说明。
6. 修复重要问题时,更新 TROUBLESHOOTING.md。
7. 重要版本变化时,更新 CHANGELOG.md。
文档必须以实际代码为依据。
不要为了让文档看起来完整而编造内容。
如果没有发生需要更新文档的变化,
请明确说明本次无需修改技术文档。
这样,每次开发任务结束后,Agent 都会检查相关文档是否需要同步更新。
进一步:使用 Git 检查文档是否遗漏
可以查看本次代码变化:
git diff --stat
查看具体修改:
git diff
然后让 AI 对照修改记录检查文档:
请检查当前 Git 工作区的代码变化。
对比以下文档:
- PROJECT_GUIDE.md
- API_DOCUMENTATION.md
- DATABASE_DESIGN.md
- DEPLOYMENT.md
判断本次代码变化是否需要同步更新文档。
请列出:
1. 修改了哪些业务功能。
2. 哪些文档受到影响。
3. 哪些内容已经更新。
4. 哪些内容仍然缺失。
只处理与本次代码变化直接相关的文档。
不要修改无关文档。
如果希望自动化,可以进一步将文档检查加入 CI 流程。不过,文档内容是否准确,仍需要结合代码和测试结果进行审核。
八、使用 GitHub Actions 自动检查文档
对于使用 GitHub 管理的项目,可以通过 GitHub Actions 自动执行文档格式检查。
例如,使用 Markdownlint 检查 Markdown 文件。
在项目中创建:
.github/workflows/docs-check.yml
写入:
name: Documentation Check
on:
push:
paths:
- "docs/**/*.md"
- "*.md"
pull_request:
paths:
- "docs/**/*.md"
- "*.md"
jobs:
markdown-lint:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 22
- name: Install Markdownlint
run: npm install -g markdownlint-cli
- name: Check Markdown
run: markdownlint "**/*.md"
这套配置可以在文档发生变化时自动检查 Markdown 格式问题,例如标题层级、列表格式和代码块格式。
需要注意:
-
这里检查的是 Markdown 格式,不是技术内容是否正确。
-
@v4、Node.js 版本等应根据项目当前 CI 环境和维护策略调整。 -
正式使用时可以将工具版本固定,并根据项目目录排除不需要检查的文件。
如果希望进一步检查 API 文档,还可以在 CI 中增加 OpenAPI 文件校验步骤。
九、AI 生成技术文档时的常见问题
1. AI 生成了不存在的接口
原因通常是 AI 根据项目描述或文件名称推测接口,而不是读取真实路由。
解决方法:
-
提供 OpenAPI JSON。
-
要求逐个核对路由定义。
-
不确定的接口标记为待确认。
-
使用实际请求验证接口是否存在。
2. 文档中的参数与实际代码不一致
例如,代码中使用 page_size,文档却写成 limit。
解决方法:
优先从 Pydantic 模型、FastAPI 路由定义和 OpenAPI 文件中提取参数,不要只依赖自然语言描述。
3. 部署手册中的命令无法运行
常见原因:
-
项目目录与文档不一致。
-
Python 虚拟环境路径错误。
-
systemd 服务名称不正确。
-
环境变量没有配置。
-
Nginx 配置与实际端口不一致。
解决方法:
让 AI 根据真实配置文件生成命令,并在测试环境逐步执行验证。
4. 文档暴露了敏感信息
需要特别注意:
-
数据库密码。
-
API Key。
-
SSH 私钥。
-
访问令牌。
-
内部服务器地址。
-
用户个人数据。
不要直接把包含真实密钥的 .env、服务器日志或配置文件提交给 AI。
可以提供脱敏后的配置示例:
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_USER=app_user
DATABASE_PASSWORD=YOUR_PASSWORD
DATABASE_NAME=my_database
其中 YOUR_PASSWORD 是占位符,不是真实密码。
5. 文档更新了,但内容反而变得混乱
不要每次都让 AI 重写整个文档。
更好的方式是:
-
找到需要修改的章节。
-
提供对应代码和原有文档。
-
只更新受影响的内容。
-
保留原有结构和格式。
-
检查其他章节是否存在冲突。
这样可以减少文档反复重写造成的信息丢失。
十、总结
AI 自动生成技术文档,可以减少重复整理代码和配置的工作,也能让项目更容易交接和维护。
在实际开发中,可以采用以下方式:
-
使用 AI 分析项目目录和核心代码,生成项目说明。
-
使用 FastAPI OpenAPI 自动生成接口规范,再让 AI 整理为 Markdown。
-
使用 MySQL 建表结构导出文件生成数据库设计文档。
-
根据真实部署配置生成 Debian 部署手册。
-
将文档统一保存在项目的
docs目录。 -
每次代码修改后,让 AI 检查相关文档是否需要同步更新。
-
使用 Git 和 CI 工具检查文档变化及格式。
需要记住:AI 负责整理和辅助编写,真实代码、实际配置和测试结果才是技术文档的最终依据。
一套好的技术文档,不仅是为了让人看懂项目,也是为了让未来的开发者能够快速接手,让自动化开发工具更准确地理解项目。
- 点赞
- 收藏
- 关注作者
评论(0)