JSON 轉 OpenAPI Schema
由 JSON 範例產生 OpenAPI 3.1.0 的結構描述。輸出是最精簡的文件:info 的標題為 Generated API、版本為 1.0.0,由範例推論出的結構描述放在 components.schemas.Root。陣列元素的形狀不同時會合併成一個結構描述,只有每個元素都有的鍵才會放進 required。像 2024-01-02T03:04:05Z 這樣的日期時間字串會加上 format: date-time,null 則成為 3.1 寫法的 type: "null"。可貼到 Swagger Editor 等工具檢視,但 paths 是空的,端點請自行補上,description、example、enum 等限制也要手動加入。所有處理都在瀏覽器內完成,JSON 不會被傳送。
指南使用方式與特色
- 將 JSON 貼入輸入框後點擊「轉換成 OpenAPI」。
- 物件會展開為帶 properties 與 required 的 JSON Schema。
- 陣列會推斷元素型別;若混合多種型別則使用 oneOf。
- 可使用複製或清除按鈕來重複利用或重新開始。
範例輸入與輸出範例
Infer schema from a profile object
{"name":"Jane","email":"jane@example.com","verified":true}{
"type": "object",
"properties": {
"name": {"type": "string"},
"email": {"type": "string", "format": "email"},
"verified": {"type": "boolean"}
},
"required": ["name", "email", "verified"]
}FAQ常見問題
會輸出什麼樣的 OpenAPI 文件?
輸出最精簡的 OpenAPI 3.1.0 文件。`info` 的標題為 `Generated API`、版本為 `1.0.0`,`paths` 為空,由範例推論出的結構描述放在 `components.schemas.Root`。可以在 Swagger Editor 等工具中使用嗎?
可以。貼上輸出後即可檢視 `Root` 結構描述。`paths` 是空的,端點請自行補上。陣列元素的形狀不同時會怎樣?
會合併成一個結構描述。只有每個元素都有的鍵才會放進 `required`,只有部分元素才有的鍵則不會。只有在值的種類不同時才會使用 `oneOf`。日期時間字串如何處理?
`2024-01-02T03:04:05Z` 這類 ISO 8601 日期時間,會成為 `type: string` 並加上 `format: date-time`。只有日期的 `2024-01-02` 則只是一般的 `string`。`null` 與空陣列如何處理?
`null` 會成為 `type: "null"`(3.1 的寫法)。空陣列因無法得知元素形狀,會成為 `items: {}`。輸入的 JSON 會被傳送嗎?
不會。轉換完全在瀏覽器內進行。
使用情境常見的使用情境
起草結構描述
將 JSON 範例轉成 OpenAPI 結構描述雛形,作為文件或模擬資料產生的起點。快速分享端點的預期
轉換請求/回應範例並貼到 PR 或 issue,對齊契約細節。檢查與現有規格是否一致
將產生的雛形與現有定義比較,找出需要更新的欄位。
注意注意事項與限制
`paths` 是空的
不含端點(路徑、方法、請求、回應)。輸出的是 `components.schemas` 的結構描述。是從單一範例推論的
不含 `description`、`example`、`enum`,以及長度或範圍的限制。請依規格手動補上。採用 OpenAPI 3.1 的寫法
`null` 會成為含 `type: "null"` 的 `oneOf`,不使用 `nullable: true`。以 3.0 以前為前提的工具需要改寫。是否必填取決於範例
陣列所有元素都有的鍵會放進 `required`。即使只是範例中碰巧都有的鍵也會成為必填,請對照實際規格確認。
簡介關於此工具
JSON 轉 OpenAPI Schema 產生器
將 JSON 範例轉成 OpenAPI schema,用於 request、response 與 components.schemas 文件化。可以快速建立 schema 初稿,減少手動撰寫每個 property 的時間。
適合使用的情境
- 文件化 endpoint:從實際回應開始建立 schema。
- 整理 API 合約:檢查型別、required 欄位與巢狀結構。
- 準備 Swagger 文件:快速產生 OpenAPI schema 草稿。
format、enum、optional field、array 限制等細節仍需要人工確認。
這個工具的相關文章
JSON 轉 OpenAPI Schema 的原理|支援 Swagger 的免費線上工具
說明 JSON 如何被轉換成 OpenAPI 3.1 的 components 結構定義。涵蓋型別推導規則、陣列型別混雜時如何轉成 oneOf、日期字串的自動偵測,以及生成後該檢查的重點。
JSON 格式化與驗證:安全檢查 API 回應的方法
了解如何格式化 JSON、找出語法錯誤、確認值的型別,並將 API 回應延伸成 TypeScript 型別、Zod Schema 或 OpenAPI 文件,整理出實務上的完整流程。
JSON 生態系統入門:用實例串起格式化、型別生成、驗證與 API 定義
以一個 API 回應為例,用實際程式碼串起格式化、TypeScript 型別、Zod 執行期驗證與 OpenAPI 定義,讓你看清型別安全 API 開發的全貌。
JSON Schema 與 Zod 雙向轉換的原理|required 與 .optional() 的對應
解析雙向轉換器的實作:把 JSON Schema 轉成 Zod 結構定義,也把 Zod 程式碼轉回 JSON Schema。內容涵蓋 required 與 .optional() 預設值相反的陷阱、限制條件對照表,以及不執行程式碼就完成剖析的做法。
