项目地址：https://github.com/teng00123/git-api-gateway-doc
欢迎 Star ⭐，欢迎提 Issue / PR

---

先说痛点

做后端的同学都懂——每次改完接口，最头疼的不是代码，是文档。

• 刚上线的需求，PM 问：“这个接口的参数能不能整理一下发我？”
• CR 里有人问：“你新加的这个接口，文档在哪？”
• 隔了两周，自己都忘了改了哪几个接口，需要对着 git log 一条条翻

文档不是不想写，是太麻烦了。

一个接口要写：路径、方法、请求参数、响应字段、示例、错误码……
写一遍两遍还行，改了十几个接口？那就是纯体力活了。

我受够了，就做了这个工具：git-api-gateway-doc。

---

它做什么？

一句话：把 git diff 的输出，自动转成标准化的 API 文档。

你只需要跑一行命令，工具会：

1. 扫描 diff 里的 urls.py / views.py 变更
2. 识别哪些接口是新增、哪些是变更
3. 自动提取路径、HTTP 方法、参数信息
4. 按模板渲染成 Markdown，每个接口单独一个文件

---

快速上手（3 步搞定）

Step 1：导出 diff

git diff HEAD~1 > changes.diff
# 或者对比分支
git diff main..feature/your-branch > changes.diff

Step 2：解析 diff → 结构化 JSON

python3 scripts/parse_git_diff.py \
  --diff-file changes.diff \
  --output api_doc.json

Step 3：用模板渲染成 Markdown

python3 scripts/generate_md.py \
  --input api_doc.json \
  --split \
  --output-dir api_docs/ \
  --api-template-file assets/default_template.md

跑完之后，api_docs/ 目录下就有了按接口分文件的标准文档：

api_docs/
├── POST_inventory_transfer-stock.md
├── GET_users_pk_profile.md
└── PATCH_orders_id.md

每个文件长这样：

### 新增 | `POST` /inventory/transfer-stock

**描述：** 库存划拨接口  
**来源：** `inventory_management/views.py`  
**认证：** 需要

#### 请求参数

| 参数名称     | 参数类型 | 必选 | 描述         |
|------------|--------|------|------------|
| from_loc   | string | 是   | 划出仓位      |
| to_loc     | string | 是   | 划入仓位      |
| quantity   | integer| 是   | 数量         |

#### 请求示例

\```json
{
  "from_loc": "A01",
  "to_loc": "B03",
  "quantity": 100
}
\```

#### 响应示例

\```json
{
  "code": 0,
  "message": "success",
  "data": {
    "transfer_id": "TRF-20240331-001"
  }
}
\```

干净、统一、立即可用。

---

AI 增强模式（可选）

如果你嫌自动生成的字段描述太简单，可以开 AI 增强：

# 导出需要 AI 填写的任务清单
python3 scripts/enrich_api_doc.py --export-prompts \
  -i api_doc.json \
  -o prompts.json

prompts.json 里每条任务都打包好了 prompt，让 AI（比如 ChatGPT / Copilot / 你们的内部大模型）批量返回字段描述，然后一键写回：

python3 scripts/enrich_api_doc.py --apply-results \
  -p prompts.json \
  -i api_doc.json \
  --inplace

设计上每个接口只调一次 AI（把所有字段打包进一个 prompt），不会因为字段多就爆调用次数。平台无关，任何 AI 都能用。

---

支持的模板

内置两套：

模板	适合场景
default_template.md	完整格式，含请求/响应参数、示例、错误码
minimal_template.md	精简格式，只保留核心字段，快速交付

也支持自定义模板，用 $变量名 占位，想要什么格式自己定。

---

一键端到端命令

不想分步跑？一条管道搞定：

git diff HEAD~1 > changes.diff && \
python3 scripts/parse_git_diff.py -d changes.diff -o api_doc.json && \
python3 scripts/generate_md.py \
  -i api_doc.json \
  --split \
  --output-dir api_docs/ \
  --api-template-file assets/default_template.md

---

适合谁用？

• 用 Django / DRF 写后端的同学（当前版本解析 Django 路由格式）
• 经常改接口、需要输出文档给前端 / PM / 网关平台的场景
• 想把 API 文档生成集成进 CI/CD 流程的团队

---

当前状态 & 未来计划

这个工具我是从自己项目里抽出来的，目前支持 Django/DRF，核心功能稳定可用。

后续想做的：

• 支持 FastAPI / Flask 项目的 diff 解析
• 输出 OpenAPI / Swagger 格式
• 提供 GitHub Actions 模板，diff → 文档自动提交到 wiki

如果你有用得上的场景，欢迎来 Star 支持一下，也欢迎提 Issue 说说你的需求——优先级直接参考 Issue 数量 😄

---

写在最后

做这个工具的初衷很简单：不想让文档成为阻碍快速迭代的负担。

代码改了，文档也应该能跟上。手动维护既耗时又容易漏，不如让工具盯着 diff，自动帮你把该写的写了。

如果你也觉得写 API 文档是件烦人的事，试试看吧。

项目地址：https://github.com/teng00123/git-api-gateway-doc
Star ⭐ 是最直接的支持，谢谢！

---

标签：#Python #Django #DRF #API文档 #开发效率 #工具分享 #git #自动化