JSON → GraphQL — JSON から GraphQL Schema を生成
JSON データから GraphQL schema の型定義を生成します。ネストされたオブジェクト型、配列、null 許容フィールドに対応。ブラウザで完結、アップロード不要。
JSON to GraphQL Schema
Generate GraphQL schema type definitions from JSON data. Auto-detects types, nullable fields, arrays, and nested objects. Works entirely in your browser.
GraphQL schema は現代の Web API 設計における最も強力な契約です。schema はあらゆる型、あらゆるフィールド、あらゆる引数、あらゆるレスポンスの形状を定義し、クライアントとサーバーは同じ schema からコードを生成することで API の表面が一貫したまま保たれます。サンプル API レスポンスから schema を手で書くことは、既存の REST や RPC API に GraphQL を導入する第一步であり、生成された schema は resolver マップの足場として機能します。生成器は JSON レスポンスを走査し、ネストされた各オブジェクトに対して GraphQL の型システムを推測して、サーバー側 resolver がそのまま読める SDL ファイルを出力します。
実際の現場で特に重要になる GraphQL 固有の論点は、「null 許容をデフォルトにする」か「非 null 許容をデフォルトにする」か、という点です。非 null 許容のフィールド（String!）は、そのフィールドが常に存在することをクライアントに約束するものであり、サーバーはあらゆるリクエストでその約束を守らなければなりません。非 null 許容のフィールドを後から null 許容に変更するのは破壊的変更です。生成器はデフォルトでは、サンプル配列のすべての要素に現れるフィールドを非 null 許容にしますが、進化する API にとってはすべてのフィールドを null 許容にして、クライアントが値の不在を適切に処理できるようにする方が安全です。オプションにある null 許容のトグルはそのために存在しています —— API がまだ開発段階で、レスポンス形状が変わり得る場合はこちらを選択してください。
schema を生成した後によく取られる次のステップは、コード生成パイプラインへ接続することです。TypeScript クライアント向けの graphql-codegen、Go サーバー向けの gqlgen、Apollo エコシステム向けの apollo-tooling などです。生成された SDL はこれら 3 つの共通の入力になります。出先がモックサーバーであれば、同じ JSON サンプルを companion の JSON-to-TypeScript 変換器にも渡して TypeScript 型を生成でき、モックサーバーの戻り型と GraphQL schema を同じソースから定義できます。
使い方
JSON API レスポンスを貼り付ける
REST または GraphQL エンドポイントから JSON オブジェクトを投入します。生成器が構造を走査し、ネストされた各オブジェクトの形状に対応する GraphQL schema の型定義を出力します。
schema のスタイルを選択
SDL（Schema Definition Language、標準の .graphql 形式）と JSON 記法を切り替えます。あらゆるフィールドが存在しない可能性がある API のために、「null 許容をデフォルトにする」を有効化できます。
schema をコピー
SDL または JSON schema をクリップボードにコピーします。出力は Apollo Server、GraphQL Yoga、gqlgen にそのまま貼り付けられます —— 余計な整形は不要です。
よくある質問
JSON 型を GraphQL の scalar 型にどのように対応付けますか？
JSON の文字列は `String` に、数はサンプルに小数点が含まれるかに応じて `Int` か `Float` に、真偽値は `Boolean` になります。ISO 8601 の日付文字列は自動検出され、カスタムの `DateTime` scalar に対応付けられます（scalar は resolver マップで定義してください）。
GraphQL のリストには対応していますか？
はい。JSON 配列は schema では `[Type]` になります。オブジェクトの配列は `[NestedType]` に、scalar の配列は `[String]`、`[Int]` などになります。生成器はサンプル配列の最初の要素からリストの要素型を推測します。
GraphQL の mutation や query はどうですか？
生成器が出力するのは型定義のみです —— query、mutation、subscription は含まれません。resolver は手書きしてください。出力された型は `graphql-codegen`、`gqlgen`、または任意の GraphQL ライブラリへの入力になります。
mutation 用の input 型を生成できますか？
はい —— 出力オプションで「input 型」を有効にすると、`type` 定義の代わりに `input` 型を出力します。Input 型は mutation の引数、つまりクライアントからサーバーへデータを送る場面で使用します。
null 許容性はどのように判定されますか？
デフォルトでは、サンプル配列のすべての要素に現れるフィールドは非 null 許容（`String!`）、一部の要素に欠けているフィールドは null 許容（`String`）になります。「null 許容をデフォルトにする」を有効にすると、すべてのフィールドが null 許容になります —— 進化し続ける API にとってはより安全な選択です。
制限事項
- union 型・interface 型には非対応生成器が出力するのは object 型と scalar 型のみです。GraphQL の union（多態的なレスポンス用）と interface 型はフラットな JSON からは推測できません —— 生成後に手動で定義してください。
- enum は検出しない'pending'、'active'、'closed' のみを取る文字列フィールドは、GraphQL enum ではなく String として出力されます。取りうる値が既知のフィールドについては、出力を確認のうえ手動で enum を追加してください。
- 型推論はサンプルに依存サンプルでは文字列であるフィールドが、同じエンドポイントからの別のレスポンスでは Int である可能性があります。生成器は与えられたサンプルからのみ型を推測します —— API のレスポンス形状が一貫しない場合は、複数のサンプルで検証してください。
プラットフォーム別の注意点
- macOS
- 生成された SDL は Apollo Studio、GraphQL Playground、およびあらゆる GraphQL IDE にそのまま貼り付けられます。プロトタイピング中にサンプル API レスポンスから schema を一度だけ生成したい場合、ブラウザツールが適しています。
- Windows
- 生成された SDL は Windows 上の Altair GraphQL Client や GraphiQL でそのまま使えます。バックエンドのエンドポイントがまだ文書化されていないクライアントサイド開発で、その場限りの生成を行う場合に利用してください。
- Linux
- コマンドラインの作業では、`graphql-codegen` や `apollo-tooling` で稼働中のエンドポイントを introspection できます。エンドポイントが未デプロイである、または認証層の背後にある場合は、ブラウザツールが適切な選択肢です。
- Web
- 完全にクライアントサイドで動作します。オフラインでも利用可能。API の設計段階で静的な JSON fixture ファイルから schema を生成する際に便利です。