API 文件產生器 是做什麼的?
此技能能從程式碼庫中的 API 路由檔案自動產生 OpenAPI 3.0 (Swagger) 文件。
何時使用此技能
- 使用者要求產生 API 文件
- 處理 REST API 端點
- 需要建立或更新 OpenAPI/Swagger 規格
- 為 Express、FastAPI、Flask、NestJS 或類似框架設定 API 文件
操作說明
1. 探索 API 路由
搜尋程式碼庫中的 API 路由定義:
- Express/Node.js:尋找
app.get()、app.post()、router.get()等 - FastAPI/Python:尋找
@app.get()、@router.post()裝飾器 - Flask:尋找
@app.route()裝飾器 - NestJS:尋找
@Get()、@Post()、@Controller()裝飾器 - Rails:尋找
config/routes.rb中的路由
使用 Glob 來尋找路由檔案 (例如:**/*routes*.{js,ts,py}、**/controllers/**/*.{js,ts})
2. 分析路由模式
對於每個發現的路由,提取:
- HTTP 方法:GET、POST、PUT、PATCH、DELETE
- 路徑:端點 URL (例如:
/api/users/:id) - 參數:路徑參數、查詢參數、請求主體
- 回應:預期的回應結構
- 身份驗證:是否需要驗證
- 描述:路由附近的註解或文件字串
3. 產生 OpenAPI 規格
建立或更新 OpenAPI 3.0 規格檔案 (通常為 openapi.yaml 或 swagger.json):
- 從
templates/openapi-3.0.yaml範本開始 - 將每個路由對應到 OpenAPI 路徑物件
- 使用 JSON Schema 定義請求和回應的結構
- 包含參數定義 (路徑、查詢、主體)
- 若偵測到身份驗證機制,請加入驗證方案 (Bearer、API Key、OAuth2)
- 使用標籤將端點分組 (例如「使用者」、「產品」、「驗證」)
4. 驗證完整性
檢查產生的文件是否包含:
- 所有已發現的端點
- 準確的 HTTP 方法和路徑
- 盡可能包含請求和回應的範例
- 錯誤回應 (400、401、404、500 等)
- 安全要求
5. 輸出位置
- 儲存為專案根目錄下的
openapi.yaml,或 - 若
docs/或api/目錄存在,則放置於其中 - 若不明確,請詢問使用者的偏好位置
框架特定備註
Express/Node.js
- 檢查可能影響驗證/驗證的中介軟體
- 尋找請求驗證器 (Joi、express-validator 等)
- 提取 JSDoc 註解作為端點說明
FastAPI
- FastAPI 會自動產生 OpenAPI 文件,但此技能可增強這些文件
- 提取 Pydantic 模型作為請求和回應的結構
- 檢查
response_model和status_code參數
NestJS
- 尋找 DTO (資料傳輸物件) 作為結構
- 檢查 Swagger 裝飾器 (
@ApiOperation、@ApiResponse) - 從控制器和方法裝飾器中提取元數據
最佳做法
- 使用現有結構:若程式碼庫中有 TypeScript 介面、Pydantic 模型等,請使用它們來獲得準確的結構
- 包含範例:若有測試案例,請從中提取請求和回應範例
- 邏輯分組:使用標籤依照資源或功能區域組織端點
- 適當版本:使用程式碼庫中的 API 版本 (例如「1.0.0」)
- 加入說明:使用程式碼註解/文件字串作為端點說明
支援檔案
templates/openapi-3.0.yaml:基礎 OpenAPI 範本examples.md:框架特定範例