api-docs-generator

api-docs-generator 是一項專業的軟體代理技能，旨在縮短不斷演進的原始程式碼與技術文件之間的差距。透過監控程式碼變更，此工具確保 API 規格保持精確且易於存取，無需手動介入。它專為管理複雜後端服務並需要跨格式（包括 OpenAPI 和 Markdown）保持一致文件的工程團隊與開發人員而建。其主要目標是最大限度地減少手動更新的負擔，降低程式碼實作與文件之間出現差異的可能性。

• 自動分析儲存庫程式碼變更，以偵測對 API 端點與架構的影響。

• 直接從原始程式碼註釋生成並維護結構化的 OpenAPI 規格。

• 更新並同步專案層級的 Markdown 文件，以反映架構上的變更。

• 與 GitHub Pages 等文件託管平台整合，實現無縫部署。

• 在解析或部署失敗期間提供全面的錯誤處理與平滑降級機制。

• 確保不同文件格式之間的長期一致性，防止資訊過時。

• 適用於高頻率更新的專案，其中保持文件同步是每週營運的一大挑戰。

• 最適合由涉及公開 API 簽章或介面變更的 git commit 或 pull request 觸發。

• 輸入為乾淨且帶有註釋的原始程式碼；輸出為人類可讀的 Markdown 及機器可讀的 JSON/YAML OpenAPI 檔案。

• Token 預算管理是核心優先事項，針對 Claude Code 生態系統中的每週循環營運進行了優化。

• 建議與靜態分析工具及程式碼審查子代理結合使用，以實現完整的「文件即程式碼」(Documentation-as-Code) 工作流程。

• 若解析自訂語言或非標準 API 裝飾器時，請注意此技能的複雜依賴需求。