openapi-spec-generator

OpenAPI Spec Generator 是一款專為工程團隊設計的技術技能，旨在架起後端開發與 API 文檔之間的橋樑。它能自動生成符合行業標準的 OpenAPI 3.0 和 3.1 規範，確保 API 合約的準確性與可讀性。此工具非常適合優先採用 API 設計先行策略或需要維護現有代碼與文檔一致性的軟體工程師、後端開發者及系統架構師。透過直接整合到開發工作流中，它消除了手動維護文檔的需求，從而減少了 API 邏輯與介面定義之間的偏差。

• 自動從 FastAPI、NestJS 和 Express 的框架特有裝飾器與模型生成 OpenAPI 規範。

• 支援手動編寫完整的 YAML 規範，包含 Info、Servers、Paths、Components（架構/參數）以及 Security（Bearer, OAuth2, API Key）。

• 促進強大的 TypeScript 和 Python API 客戶端 SDK 的自動生成，簡化前端與跨服務整合。

• 提供模擬伺服器的快速設置，實現前後端開發週期的解耦。

• 實現與 Swagger UI、ReDoc 和 Stoplight 等互動式文檔套件的無縫整合。

• 支援進階 API 實踐，如合約測試、請求/響應驗證以及包含請求/響應範例的複雜架構定義。

• 當啟動新的 API 先行設計並在實現前定義介面，或為現有的 RESTful 服務補充文檔時，請使用此技能。

• 輸入通常包括原始程式碼檔案、Pydantic 模型或結構化的 YAML 組件定義；輸出為生產級的 JSON/YAML 規範檔案或生成的客戶端庫。

• 請確保所有安全架構均在組件部分明確定義，以正確記錄身份驗證要求。

• 利用提供的 FastAPI 和 NestJS 範本，確保裝飾器與註解能正確映射到 OpenAPI 定義。

• 對於合約測試，請將生成的規範作為單一事實來源，用於跨整合測試驗證請求/響應負載。

• 產生器嚴格遵循 OpenAPI 3.0/3.1 標準，支援複雜的嵌套物件結構、遞迴架構以及細粒度的驗證規則，例如 minLength、maxLength 和格式約束。