從 JSON 建立 OpenAPI (Swagger) 結構定義

什麼是 OpenAPI Specification (OAS)？

OpenAPI Specification (OAS) 是用於描述 RESTful API 介面的標準規範，其特點是與特定電腦語言無關。過去被稱為「Swagger」，目前則作為由社群主導的開放項目進行管理。

它通常以 YAML 或 JSON 格式撰寫，已成為自動化現代開發流程中不可或缺的存在：

• API 文件自動生成：透過 Swagger UI 等工具建立互動式文件。
• 客戶端程式碼生成：自動輸出各種語言的 SDK（函式庫）。
• 建立 Mock 伺服器：建立虛擬伺服器，讓前端開發得以先行。
• 品質控管：對請求與回應進行結構驗證（Schema Validation）。

結構定義中的「嵌套」挑戰

在建立 API 規格書時，最耗時的工作通常是定義請求主體（Request Body）或回應主體（Response Body）的「Schema（結構描述）」。

面對層級深厚（嵌套）的物件，或具有眾多屬性的 JSON，要手動配合 OpenAPI 結構（type, properties, required, items 等）進行撰寫，不僅費時，更常成為輸入錯誤的根源。

從 JSON 進行高效的自動生成

如果您已有正在運作的 API，或手邊有範例回應 JSON，那麼以此為基礎自動生成結構定義是最有效率的方法。

1. 執行 API，取得實際的 JSON 資料。
2. 將該 JSON 貼到 JSON 轉 OpenAPI 生成工具 中。
3. 數秒內即可產出 components/schemas 格式的定義。
4. 將生成的定義整合到您的 openapi.yaml 等規格檔案中。

本站工具的特點

DevToolKits 的生成工具是基於最新的 OpenAPI 3.1.0 標準運作。

• 型別推導：準確判別數值、字串、真假值、物件與陣列。
• 提取必要項目：自動將 JSON 中包含的屬性列為 required（必要）項目（可視需求後續調整）。
• 型別整合 (oneOf)：當陣列中混雜不同型別的資料時，使用 oneOf 完整呈現多種型別。
• 偵測日期格式：偵測如 2024-01-15T12:00:00Z 般的字串，並自動加上 format: date-time。
• 遵循 OpenAPI 3.1：針對最新規範進行優化，例如使用 type: "null" 取代 nullable: true。

💡 專業提示：自動生成僅提供「草稿」。生成後，請為各個屬性手動添加 description（描述）或 example（範例），這將能磨練出一份對團隊成員或 API 使用者更親切且實用的文件。