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

  來源於7w4.net。

• 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 文件的開發者。