什麼是 OpenAPI Specification (OAS)?
OpenAPI Specification (OAS) 是一套用於描述 RESTful API 介面的標準規範，具有獨立於程式語言的特性。它最初被稱為 Swagger，目前由社群驅動的開源專案維護。
OAS 以 YAML 或 JSON 格式編寫，已成為自動化開發生命週期中不可或缺的一部分：
- 互動式文件：利用 Swagger UI 等工具生成即時且互動的 API 文件。
- 程式碼生成：自動為數十種語言生成用戶端 SDK 或伺服器 stub。
- 模擬測試 (Mocking)：建立模擬伺服器，讓前端開發在後端完成前即可先行啟動。
- 驗證：確保請求與回應數據符合定義好的 Schema。
嵌套 Schema 定義的挑戰
在撰寫 API 規格文檔時，定義請求或回應主體的「Schema」部分通常是最繁瑣的工作。
手動編寫具有深層嵌套結構或包含多個屬性的 JSON 對應的 OpenAPI 規格（包括 type, properties, required, items 等），不僅效率低下，還容易產生人為錯誤。
從 JSON 高效自動生成
如果您已經有運行中的 API 或範例回應 JSON，那麼自動生成 Schema 是建立文件最快的方式。
- 執行 API 呼叫以獲取真實的 JSON 回應。
- 將該 JSON 貼入我們的 JSON 轉 OpenAPI 轉換工具。
- 工具會在數秒內生成
components/schemas定義。 - 將生成的部分整合到您的
openapi.yaml或openapi.json中。
為何選擇我們的工具？
DevToolKits 的生成器針對最新的 OpenAPI 3.1.0 標準進行了優化。
- 智慧推論：精確識別各種類型，包括整數、數字、字串、布林值、物件與陣列。
- 自動必填欄位：根據 JSON 中的屬性自動列出
required項目（可依需求後續調整）。 - 混合陣列處理 (oneOf)：當陣列中包含不同類型的數據時，工具會使用
oneOf來定義每個潛在類型。 - 日期格式檢測：識別 ISO 8601 字串（如
2024-01-15T12:00:00Z）並自動標註format: date-time。 - OAS 3.1 最佳化：使用最新的類型定義（如
type: "null"），而非舊版的nullable: true。
💡 專家提示：自動生成是一個極佳的起點。為了獲得專業的文件，我們建議在生成的 Schema 中手動添加
description和example欄位，讓其他開發者或 API 使用者能更輕鬆地理解您的介面。