JSONスキーマからOpenAPI仕様への変換器 — Numio
JSON Schema（draft-04 以降）を OpenAPI 3.0 の Schema Object に変換します。"null" を含む type 配列は "nullable: true" に、const は要素が 1 つの enum に、examples は単一の example になります。
ペイロードを draft-07 のスキーマで検証しており、同じモデルを OpenAPI 3.0 ドキュメントの components/schemas でも使いたい場合。
JSON Schema
こんなときに使えます
- ペイロードを draft-07 のスキーマで検証しており、同じモデルを OpenAPI 3.0 ドキュメントの components/schemas でも使いたい場合。
- OpenAPI 3.0 のツールが "type": ["string", "null"] を受け付けず、null 許容フィールドを書き換える必要がある場合。
使い方
- JSON Schema パネルに JSON Schema を貼り付けます。送信前にページで解析するため、有効な JSON である必要があります。
- スキーマは /api/json-schema-to-openapi-schema に送信され、サーバーで変換されます。パネルにはその旨の通知が表示されます。
- Open API Schema パネルから結果をコピーし、OpenAPI ファイルの components/schemas の下に配置します。
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"kind": { "const": "invoice" },
"total": { "type": ["number", "null"], "exclusiveMinimum": 0 },
"notes": { "type": "string", "examples": ["Net 30"] }
},
"required": ["kind"]
}OpenAPI 3.0 Schema Object
{
"type": "object",
"properties": {
"kind": {
"enum": [
"invoice"
]
},
"total": {
"type": "number",
"exclusiveMinimum": true,
"nullable": true,
"minimum": 0
},
"notes": {
"type": "string",
"example": "Net 30"
}
},
"required": [
"kind"
]
}仕様と制限
入力は変換のためにサーバーのルート（/api/json-schema-to-openapi-schema）に送信されます。ブラウザ内だけで処理されるわけではありません。Next.js の API ルートが受け付けるリクエストボディは、デフォルトで 1 MB までです。
$schema キーワードは削除されます。数値の exclusiveMinimum/exclusiveMaximum は、OpenAPI 3.0 の形式である minimum/maximum とブール値のフラグに書き換えられます。
$ref の値はそのまま残り、definitions は components/schemas に移動されないため、参照パスは自分で修正する必要があります。
変換先は OpenAPI 3.0 です。OpenAPI 3.1 は JSON Schema をそのまま使うため、通常は変換不要です。
FAQ
null 許容の型はどう変換されますか？
["number", "null"] のような type 配列は、例のように "type": "number" と "nullable": true になります。
$ref 参照は解決されますか？
いいえ。ページは参照を展開しません。"$ref": "#/definitions/Tag" と definitions ブロックはそのままコピーされます。
const と examples はどうなりますか？
const は値が 1 つの enum になり、examples 配列はその最初の要素を使った単一の example に置き換えられます。