跳至內容
Schema 工具

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 限制等細節仍需要人工確認。

這個工具的相關文章

最新文章