主题
实战案例：文档自动生成
用 AI 自动生成技术文档，包括 API 文档、README、注释等。
功能目标
- 根据代码自动生成 API 文档
- 生成 README.md
- 补充函数注释
- 生成使用示例
场景一：根据代码生成 API 文档
用 AI 分析代码并生成文档
python
from openai import OpenAI
client = OpenAI()
def generate_api_doc(code, language):
"""根据代码生成 API 文档"""
prompt = f"""
分析以下 {language} 代码，生成完整的 API 文档（Markdown 格式）。
要求：
1. 列出所有公开接口（URL、HTTP 方法）
2. 每个接口的请求参数（类型、是否必填、说明）
3. 响应格式（JSON 示例）
4. 错误码说明
5. 使用示例（curl 命令）
代码：
```{language}
{code}输出格式（Markdown）：
API 文档
接口列表
GET /api/users
描述：获取用户列表
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | int | 否 | 页码 |
响应示例：
json
{{}}错误码：
| 错误码 | 说明 |
|---|---|
| 401 | 未授权 |
| """ |
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
使用
java_code = open("UserController.java").read() doc = generate_api_doc(java_code, "java") print(doc)
## 场景二：生成 README.md
```python
def generate_readme(project_path):
"""根据项目结构生成 README"""
# 1. 收集项目信息
files = []
for root, dirs, filenames in os.walk(project_path):
for f in filenames:
if f.endswith(('.java', '.py', '.js', '.md')):
files.append(os.path.join(root, f))
# 2. 读取关键文件
key_files = []
for f in ['pom.xml', 'package.json', 'README.md', 'src/main/java/...']:
if os.path.exists(os.path.join(project_path, f)):
key_files.append(open(os.path.join(project_path, f)).read())
# 3. 让 AI 生成 README
prompt = f"""
根据以下项目信息，生成一个完整的 README.md：
项目文件列表：
{chr(10).join(files[:50])} # 只取前 50 个，避免超限
关键文件内容：
{chr(10).join(key_files)}
README 应包含：
1. 项目标题和描述
2. 功能特性
3. 技术栈
4. 快速开始（安装、运行）
5. 项目结构
6. 如何贡献
7. License
使用中文，格式用 Markdown。
"""
# 调用 AI...场景三：补充函数注释
python
def add_docstring(code):
"""为没有注释的函数补充文档注释"""
prompt = """
为以下代码中的每个函数添加文档注释（JavaDoc / JSDoc 风格）。
要求：
- 描述函数功能
- 描述每个参数
- 描述返回值
- 如果有异常，描述异常
代码：
```java
{code}只输出补充了注释的代码，不要解释。 """
# 调用 AI...
## 场景四：生成使用示例
```python
def generate_usage_examples(api_doc, language):
"""根据 API 文档生成使用示例"""
prompt = f"""
根据以下 API 文档，生成使用示例代码。
要求：
- 每种主要功能都给出示例
- 使用 {language}
- 包含请求和响应处理
- 包含错误处理
API 文档：
{api_doc}
"""
# 调用 AI...集成到构建流程
在 package.json / pom.xml 中添加生成文档的脚本：
json
// package.json
{
"scripts": {
"gen-docs": "node scripts/generate-docs.js"
}
}bash
# 运行
npm run gen-docs工具推荐（开箱即用）
| 工具 | 说明 |
|---|---|
| Docusaurus | 文档网站生成 |
| Swagger/OpenAPI | API 文档自动生成 |
| JSDoc | JS 文档生成 |
| Cursor / Copilot | AI 辅助写注释 |
用 AI 生成初稿，再人工润色，效率最高。