AI 自动生成技术文档:接口文档、项目说明与部署手册

举报
yd_228838069 发表于 2026/11/19 14:54:58 2026/11/19
【摘要】 一、为什么需要自动生成技术文档?在软件开发过程中,代码通常会随着功能迭代不断变化,但技术文档却容易被忽略。例如:新增了 API 接口,却没有及时更新接口说明。修改了数据库字段,项目说明仍然使用旧结构。更换了部署方式,部署手册没有同步更新。项目开发人员发生变化,接手者难以快速理解代码。这些问题会增加项目维护成本。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 部署手册

部署文档是项目交付中非常重要的一部分。

一个完整的部署手册,至少应该说明:

  1. 服务器环境要求。

  2. 软件依赖。

  3. 项目目录。

  4. 环境变量配置。

  5. 数据库初始化。

  6. 后端启动方式。

  7. 前端构建方式。

  8. Nginx 配置。

  9. HTTPS 配置。

  10. 服务重启和更新方式。

  11. 日志查看和故障排查。

  12. 备份与恢复。

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 重写整个文档。

更好的方式是:

  1. 找到需要修改的章节。

  2. 提供对应代码和原有文档。

  3. 只更新受影响的内容。

  4. 保留原有结构和格式。

  5. 检查其他章节是否存在冲突。

这样可以减少文档反复重写造成的信息丢失。


十、总结

AI 自动生成技术文档,可以减少重复整理代码和配置的工作,也能让项目更容易交接和维护。

在实际开发中,可以采用以下方式:

  1. 使用 AI 分析项目目录和核心代码,生成项目说明。

  2. 使用 FastAPI OpenAPI 自动生成接口规范,再让 AI 整理为 Markdown。

  3. 使用 MySQL 建表结构导出文件生成数据库设计文档。

  4. 根据真实部署配置生成 Debian 部署手册。

  5. 将文档统一保存在项目的 docs 目录。

  6. 每次代码修改后,让 AI 检查相关文档是否需要同步更新。

  7. 使用 Git 和 CI 工具检查文档变化及格式。

需要记住:AI 负责整理和辅助编写,真实代码、实际配置和测试结果才是技术文档的最终依据。

一套好的技术文档,不仅是为了让人看懂项目,也是为了让未来的开发者能够快速接手,让自动化开发工具更准确地理解项目。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。