入力

出力

GraphQL ビューアって何？

GraphQL の SDL をどこかから貼り付けたら 1 行に潰れて返ってきて、読もうとして詰まったことがあるなら、その問題のことです。型・フィールド・引数・ディレクティブ・ユニオンメンバーが全部くっついて構造が消えてしまいます。このツールはそれを直します。左のパネルにスキーマを貼り付けると、右のパネルが 2 スペースインデント、1 行 1 フィールド、引数はインライン、ブロック文字列の説明はそれが説明する型やフィールドの上に残した形でレンダリングします。

整形ロジックは自前 — graphql の npm パッケージはページに読み込まれていないので、初回表示は軽いままです。SDL をトークン化し、波括弧の構造をたどって、2021 年 10 月版 GraphQL 仕様に沿った一貫した間隔で再出力します。実務で実際に見る SDL の構文はひととおりカバーしています：type、interface、union、enum、input、scalar、extend、schema、リスト・非 null 修飾子（[Foo!]!）、デフォルト値、ディレクティブ、三重引用符の説明文。すでに整形済みの入力はそのまま同じ出力に戻ります。

すべてブラウザ内で動きます。アップロードなし、スキーマはどこにも保存されません。貼って、読んで、コピーするだけ。

GraphQL ビューアの使い方

3 ステップで終わります。下で説明するボタンは、このページに実際にあるボタンです。

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

左の入力パネルに GraphQL のスキーマを貼り付けます。.graphql、.graphqls、.gql ファイルなら アップロード、現実っぽい EC のスキーマを読み込みたいなら サンプル を押してください。圧縮された SDL がどんな見た目かのサンプル：

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]! total:Money! status:OrderStatus!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

サーバー形式のスキーマ（extend type Query 付き）も、単独の型定義も両方動きます。受け付ける形は Apollo Server のようなツールがパースするものと同じです。

整形された出力を読む

右の出力パネルが、パース済みの SDL を 2 スペースインデントでレンダリングします。フィールド・enum 値・ユニオンメンバーはそれぞれ独自の行になります。引数はフィールド行にインラインのままなのでシグネチャが自然に読めます。ブロック文字列（"""..."""）として書かれた説明は、それが説明する型やフィールドの上に残されます。これは Relay の GraphQL 仕様がスキーマの文書化として推奨している方法です。SDL の波括弧が合っていなかったりパースエラーがあると、ビューアはクラッシュせずに親切なメッセージを表示します。

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

コピー を押すと整形済みのスキーマがプルリク・ドキュメント・チャットに使えます。ダウンロード を押すと .graphql として保存できます。入力パネルのクリアボタンで空の状態に戻ります。パースは完全にクライアントサイドで実行されます — スキーマがページから出ることはありません。

実際に使う場面

スキーマのプルリクレビュー

スキーマの PR をレビューしているのに、コードジェネレータがフォーマットを潰してしまったせいで diff が読めない？新しいバージョンをここに貼り付けて、構造を目で追って、それから diff に戻れば何が変わったかのメンタルモデルがすっきりします。チームで良いスキーマ設計とは何かを詰めているときには特に便利です。

フェデレーションとサブグラフのデバッグ

Apollo のフェデレーションゲートウェイをデバッグしていて、合成されたスーパーグラフのスキーマが巨大な塊で返ってきた？マージ済みの SDL を貼り付けて、変な挙動をしている型を見つけて、どのフィールドをどのサブグラフが担当しているかを確認します。出力に出てくるフェデレーションのディレクティブも、スキーマ構文の他の部分と同じように表示されます。

API のドキュメント化

チームが運用している GraphQL API の公開ドキュメントを書く？ビューアにスキーマを放り込んで、整形された版を Wiki や README にコピーします。型・インターフェース・ユニオンの木構造は、1 行 1 フィールドのレイアウトになると自然に読めます。

新しいエンジニアのオンボーディング

新しいメンバーがあなたの GraphQL API の形を理解しようとしている。各型の上に説明文が見える整形済みのスキーマは、コードジェン出力の整形されていない塊よりずっと優しいスタート地点です。

よくある質問

スキーマを検証してくれる？それとも整形だけ？

整形だけです。ビューアは整形に必要なぶんだけ波括弧と引用符の対応をチェックしますが、Query が存在するか、参照された型が定義されているか、ディレクティブの引数が定義と一致するかは検証しません。完全な検証には参照実装の graphql-js を使うか、サーバーの起動時チェックを通してください。

スキーマはサーバーに送られる？

いいえ。整形は完全にブラウザ内で動きます。何もアップロードされず、何もログに残りません。社内や未公開のスキーマを貼り付けても安全です。

ブロック文字列の説明文に対応している？

はい。三重引用符の説明文（"""顧客が出した注文。"""）は保持され、それが説明する型やフィールドの上の行に出力されます。これは GraphQL 仕様に沿った正規の SDL ドキュメントの書き方です。

ディレクティブやカスタムスカラーは？

両方残ります。@deprecated、@key、その他カスタムディレクティブはフィールド上にインラインのまま残ります。scalar DateTime のようなカスタムスカラーは独立した行に出力されます。ビューアはディレクティブのセマンティクスを解釈しようとはしません — それはサーバー側の仕事です。

すでに整形済みの SDL は再整形されてしまう？

べき等です — 整形済みの SDL を整形しても同じ出力になります。なので CI のチェックや貼って比較するワークフローでビューアを使っても、空白文字のずれを気にする必要はありません。

どれくらい大きなスキーマまで貼れる？

ブラウザが余裕でレンダリングできる範囲ならなんでも。型が数百個のスキーマなら問題ありません。5 MB を超えると Ace エディタ自体が遅くなり始めます — ボトルネックはパーサーではなくそこです。

その他の GraphQL ツール

表示は GraphQL を扱う作業の一部です。残りはこちらのツールでカバーできます：