openapi-spec-generation

本技能為 OpenAPI 3.1 規範的生命週期管理提供強大的框架，確保您的 RESTful API 保持良好的文件記錄並符合定義的合約。它專為軟體工程師、API 架構師與開發人員設計，協助您在開發週期中平衡速度與準確性。無論您是採用設計優先 (Design-First) 策略來啟動新專案，還是利用程式碼優先 (Code-First) 策略來完善現有程式碼庫，本工具都能提供必要的範本與結構指導，以維護清晰且機器可讀的 API 定義。

• 完整支援 OpenAPI 3.1.0 標準，包含複雜的組件 (components)、安全機制 (security schemes) 與進階綱要 (schemas)。

• 為實作設計優先、程式碼優先及混合開發工作流程提供戰略指導。

• 支援 API 文件自動化範本生成，涵蓋驗證機制、速率限制與伺服器定義。

• 提供詳細的路徑與操作管理，包含 HTTP 動詞、參數定義與標準化的錯誤回應模式。

• 透過準備符合自動化用戶端 SDK 生成與互動式 API 文件入口網站需求的規範，促進下游無縫整合。

• 針對新 API 使用設計優先方法，確保在編寫後端程式碼之前與團隊達成共識。

• 利用程式碼優先方法，從控制器與路由定義中提取元資料，確保文件內容真實反映程式碼。

• 針對持續演進的服務採用混合方法，結合手動註解與自動產生的規範片段。

• 透過引用全域組件來處理常見錯誤（如 400 Bad Request, 401 Unauthorized, 429 Rate Limited），確保錯誤處理的一致性。

• 輸入通常包含 API 端點詳細資訊、模型結構與安全需求；輸出為符合業界標準且基於 YAML 或 JSON 的有效 OpenAPI 規範。