api-doc-gen — API 文档自动生成器

痛点

• 手写 API 文档费时费力，格式不统一
• 前后端接口对接时，文档经常滞后于代码
• 不同项目文档风格不一致，维护成本高
• Swagger/OpenAPI 写起来复杂，容易出错

场景

• 写好一个 Flask/Django/FastAPI 接口，直接生成完整 API 文档
• 根据代码注释自动推断参数类型和返回值
• 导出 OpenAPI 3.0 (Swagger) JSON/YAML 格式
• 导出 Markdown 格式给非技术团队查看
• 导出 Postman Collection 方便调试

定价

• 免费：基础文档生成（Markdown 格式，单文件）
• Pro 19元：OpenAPI 3.0 + Postman Collection + 多端点支持
• Team 49元：批量处理 + HTML 文档站 + 自定义模板

支持框架

• FastAPI
• Flask
• Django DRF
• Express.js
• 通用函数/类（基于注释推断）

输出格式

• --format markdown — Markdown 格式 API 文档
• --format openapi — OpenAPI 3.0 JSON
• --format openapi-yaml — OpenAPI 3.0 YAML
• --format postman — Postman Collection JSON

指令格式

基本用法

api-doc-gen analyze <file_or_code> [选项]

示例

# 分析 Python Flask 文件
api-doc-gen analyze app.py --framework flask --format markdown

# 分析 FastAPI 代码
api-doc-gen analyze main.py --framework fastapi --format openapi

# 分析 Express.js 文件
api-doc-gen analyze routes.js --framework express --format postman

# 从代码字符串生成
api-doc-gen analyze "def hello(name: str) -> str: ..." --language python --format markdown

# 批量处理目录
api-doc-gen batch ./api/ --framework fastapi --format openapi -o docs/

字段推断规则

基于 Python type hints / JSDoc / 代码注释自动推断： - 参数类型：string, integer, number, boolean, array, object - 是否必填：默认必填，有默认值则可选 - 描述：优先使用注释，其次参数名 - 格式：email, phone, url, date, datetime 等

内置响应模板

技术细节

• 语言：Python 3.8+
• 依赖：仅标准库（无外部依赖）
• 安装：pip install -r requirements.txt
• CLI：基于 argparse

这个工具质量不错，能自动从代码生成 API 文档，省去手动写文档的麻烦。优点是支持多种框架和输出格式，智能推断参数类型，用起来比较方便。文档写得很详细，示例丰富。不足之处是有些文档描述和实际功能不太一致，细节上还需要打磨。总体来说是一个成熟可用的工具，适合需要快速生成和维护 API 文档的开发者。