既存のGraphQLサービスからJSON形式のSchemaを生成する prisma/get-graphql-schema
何度かやってるんですが、毎回何でやったか忘れてしまうので書き残し。
GraphQLのスキーマを生成したい
GraphQLではスキーマが仕様上重要なポイントになっています。
このスキーマを元に、クライアントやサーバーサイドのベースとなるソースコードを生成したりしますが、オープンなAPIにこれを取得するベーシックなアプローチは提供されていません。(ODataであれば、明示的にMetadataエンドポイントが提供されているのですが)
しかしながら、Github上でいくつかGraphQLサービスからスキーマを生成するプロジェクトがありましたので、その一つの使い方を紹介したいと思います。
対象のGraphQLサービス
おそらくオープンなGraphQLの中で一番メジャーかなと思う、Github API V4を対象としました。
Referenceはこちら。
Rootendpointはこちら
https://api.github.com/graphql
GithubのAccessToken取得
GraphQLにアクセスするために、あらかじめGithubのAccessTokenを取得しておきましょう。
GithubはOAuthでAccessTokenを取得しますが、UIから手動生成する手順も提供されていますので、今回はそれを使ってAccessTokenを取得し、使用します。
https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line
ちなみにスキーマを取得するだけなので、パーミッションは最低限だけで大丈夫です。
prisma/get-graphql-schema のインストール
スキーマファイルの生成にはGraphQL as a Service のPrismaが提供している get-graphql-schema を使います。
実行には npm が必要になるので、あらかじめインストールしておきましょう。
手順はそんなに難しくありません。まずGraphQL をコマンドから実行できるようにする「get-graphql-schema」をnpmでインストールします。
npm install -g get-graphql-schema
スキーマファイルの生成
以下のようなコマンドで対象のGraphQL API を指定すれば、カレントフォルダにスキーマファイル(JSON形式)が生成されます。
get-graphql-schema -h 'Authorization=Bearer <取得したAccessToken>' https://api.github.com/graphql > schema.graphql
ちなみにパラメータとして-jを渡すとJson形式で生成可能です。
get-graphql-schema -j -h 'Authorization=Bearer <取得したAccessToken>' https://api.github.com/graphql > schema.json
スキーマファイル生成後の使い道
最近Postmanのアップデートに伴いGraphQLリクエストをサポートしました。
しかも、スキーマファイルを取り込むことで、オートコンプリートを有効化し、GraphQLクエリを入力しやすくできます。
これこれ、これがやりたかったのだ。
— Kazuya Sugimoto (@sugimomoto) August 25, 2019
Github GraphQLからスキーマを生成して、Postmanに取り込み、オートコンプリートを有効化。 pic.twitter.com/vx6CKR7tel