イントロスペクションJSON

GraphQL SDL

イントロスペクションJSON to SDLコンバーターとは?

Apollo Studio、Postman、Insomniaからスキーマを取得したり、稼働中のエンドポイントに対してget-graphql-schemaを実行したりすると、返ってくるのはあなたが書いたあの読みやすいSDLではありません — それはquery { __schema { ... } }の結果、つまり600行を超えるネストされたJSONで、すべての型、すべてのフィールド、すべての修飾子がkind / name / ofTypeオブジェクトのツリーで記述されたものです。ツールには有用ですが、人間には読めません。このコンバーターはそのJSONを受け取り、実際にリポジトリにコミットするであろうSDLとして出力し直します。2021年10月版GraphQL仕様のイントロスペクションルールに従っています。

すべてはブラウザ内で行われます — アップロードなし、AIなし、スキーマがどこにも送信されません。変換ロジックは、graphql-jsが内部でbuildClientSchemaとprintSchemaを使ってやっていることをそのまま再現します。__schemaツリーを走査し、イントロスペクション専用の型(__Schema、__Type、__Field、…)と組み込みスカラーをスキップし、残りの各定義を説明文、フィールド、引数、デフォルト値、非推奨理由をそのまま出力します。完全な{ "data": { "__schema": ... } }のエンベロープを貼り付けても、{ "__schema": ... }だけでも、あるいは裸の__schema値だけでも、ページは3つすべてに対応します。

出力はまずスカラー、次にenum、インターフェース、ユニオン、入力型、最後にオブジェクト型の順にグループ化されます — 各グループ内ではアルファベット順、インデントは2スペース、定義間は空行1つです。リポジトリの<code>.graphql</code>ファイルにそのまま投入できる程度には冪等です。

コンバーターの使い方

3ステップ。下のボタンはこのページの実際のボタンです。

貼り付ける、アップロードする、サンプルを読み込む

左の入力パネルにイントロスペクションJSONを貼り付けてください — 入力を止めてからほんの一瞬で自動的に変換されるので、Convertボタンを探す必要はありません。Apollo StudioやPostmanからエクスポートした.jsonファイルを使うならアップロードを、現実的なOrder/Customer/Moneyのイントロスペクション結果をロードするならサンプルを押してください。典型的な貼り付けはこんな感じで始まります:

{
  "data": {
    "__schema": {
      "queryType": { "name": "Query" },
      "types": [
        { "kind": "OBJECT", "name": "Order", "fields": [...] },
        ...
      ]
    }
  }
}

内側の{ "__schema": ... }値や、裸の__schemaオブジェクトを貼り付けてもOKです — ページは3つの形すべてを試します。get-graphql-schemaやApollo Serverのイントロスペクションエンドポイントは、デフォルトでこれらのいずれかの形を出します。

SDL出力を読む

右の出力パネルがスキーマをSDLとしてレンダリングします。各型は2スペースのインデントで独立した定義になり、フィールドは1行ずつ、説明文は型やフィールドの上にトリプルクォートのブロック文字列として保持され、非推奨理由は@deprecated(reason: "...")として同じ行にレンダリングされます。組み込みスカラーと__イントロスペクション型はフィルタリングされ、サーバーが公開しているスキーマそのものが、RelayのGraphQL仕様が推奨するドキュメント形式で得られます。JSONが壊れていたり__schemaフィールドが欠けていたりすると、スタックトレースの代わりに分かりやすいインラインメッセージが出ます。

コピーまたはダウンロード

PRの説明、ドキュメント、チャットにSDLを貼るにはコピーを押してください。schema.graphqlとして保存するにはダウンロードを — そのままリポジトリに投入できます。入力パネルのクリアボタンで空の状態に戻せます。変換は完全にクライアントサイドで、イントロスペクション結果がページから外に出ることはありません。

実際にこれを使う場面

稼働中のエンドポイントからスキーマをキャプチャ

リポジトリにスキーマファイルがなく、稼働中のサーバーしかないGraphQLサービスを引き継ぐとき。イントロスペクションクエリを実行し、JSONをここに貼り付ければ、5分で初期のschema.graphqlがコミットできます。一度きりのためだけにgraphql-jsからbuildClientSchemaとprintSchemaを組み立てるよりラクです。

Apollo StudioやPostmanのエクスポートを読む

Apollo StudioのスキーマエクスポートはイントロスペクションJSONです。PostmanのGraphQLリクエストの「Save schema」ボタンも同じ。ここで変換すれば、JSONを目を細めて読む代わりに、コードエディタで実際にスキーマをざっと読めます。

稼働中スキーマの2つのスナップショットをdiff

staging本番に対してイントロスペクションを実行し、それぞれをSDLに変換して、2つのファイルをdiffします。フィールドの欠落やenum値のリネームを見つけるのは、SDLでは簡単ですが、生のイントロスペクションJSONではほぼ不可能です。

自分のものではないサービスから型スタブを生成

サードパーティのGraphQL APIに対してTypeScript型やReackフックが必要ですか? ほとんどのコードジェネレーターはイントロスペクションJSONではなくSDLを欲しがります。ここで変換し、SDLをcodegenパイプラインに流してください — graphql-react、graphql-codegen、あるいはあなたのスタックが使っているものへ。

よくある質問

完全な { "data": { "__schema": ... } } エンベロープが必要ですか?

いいえ。ページは3つの形を受け付けます:GraphQLレスポンスの完全なエンベロープ、{ "__schema": ... }だけ、あるいは裸の__schemaオブジェクトです。どれを貼り付けても、__schemaルートを見つけてそこから処理します。

JSONに __schema フィールドがない場合は?

分かりやすいメッセージが出ます:"Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." クラッシュなし、スタックトレースなし。

説明文と非推奨理由は保持されますか?

はい。型とフィールドの説明文は、定義の上にトリプルクォートのブロック文字列として出力されます。非推奨のフィールドとenum値は、同じ行に@deprecated(reason: "...")が付きます。これはgraphql-jsのprintSchemaの出力と一致します。

組み込みスカラーと __ イントロスペクション型はどうなりますか?

フィルタリングされます。String、Int、Float、Boolean、IDはSDLでは暗黙です — フィールドの型としてだけ現れ、トップレベルの定義としては出ません。__Schema、__Type、__Field、その他のイントロスペクションメタ型も同様です。

出力は元のイントロスペクション結果と完全にラウンドトリップしますか?

意味的にはイエス — SDLは同じスキーマを記述します。バイト単位ではノー、なぜなら型やフィールドの順序が元のソースファイルと異なる可能性があるからです。安定したdiffのために、出力は各定義グループ内でアルファベット順になっています。

イントロスペクション結果はサーバーに送信されますか?

いいえ。変換は完全にブラウザ内で実行されます。アップロードもログ記録もなし。社内サービスや未公開サービスのスキーマでも安心して貼り付けられます。

その他のGraphQLツール

SDLが手に入ったら、あとはこれらが面倒を見ます:

イントロスペクションJSONからGraphQL SDLへ