Zenn
💬

既存のGraphQLサービスからSchemaを取得する

2021/01/14に公開
GraphQL
Prisma
Apollo
GQL
tech

GitHub API v4のドキュメントをみていたのですが、自分が慣れしたんでるツールであるGraphQL Playgroundのdocsでschemaを確認したかったのですが、さくっとやり方が分からなかったので、さくっとやる方法をまとめてみました！

まずはGraphQLのSchemaの種類

  • GraphQL SDL(Schema Definition Language)
    • 拡張子は.graphql
    • 人間がSchemaを書く場合はほとんどの人はこれ
  • Introspection Result
    • 拡張子は.json
    • IntrospectionQuery という長いqueryの結果が書き出されたもの
    • 人間には読み書きしにくい

GraphQLのSchemaを取得する方法

1. 対象のGraphQLサービス

今回はGitHub API v4からschemaを取得してみます。
https://docs.github.com/en/free-pro-team@latest/graphql

2. アクセストークンの発行

こちらに従ってアクセストークンを発行してください。
https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token
権限は最低限で大丈夫です。

3. get-graphql-schemaをインストール

今回はGrapgQLのdatabase clientが提供しているパッケージを使います。
https://github.com/prisma-labs/get-graphql-schema

次のコマンドでインストールしてください

npm install -g get-graphql-schema

4. schemaの取得

get-graphql-schemaを使うと、.graphql形式でも.json形式でもどちらのschemaでも取得することができます。

.graphql形式で取得する場合

get-graphql-schema -h 'Authorization=Bearer <②で取得したAccessToken>'  https://api.github.com/graphql > schema.graphql

.json形式で取得する場合

get-graphql-schema -j -h 'Authorization=Bearer <②で取得したAccessToken>'  https://api.github.com/graphql > schema.json

GraphQLのSchemaの使い道

僕はローカルでGraphQL Playgroundのmockサーバーを立ち上げるのに使いました。
GraphQL Playgroundを使い慣れてるので、

  • ドキュメントがみやすいこと
  • queryやmutationを書きやすいこと

が僕にとっては好都合でした。
ローカルでGraphQL Playgroundのmockサーバーを立ち上げるには、以下を実行してください。

npm install -g graphql-playground-mock
graphql-playground-mock <④で取得したschemaのファイル名>

mockサーバーが起動したら、http://localhost:4000/ にアクセスするとGraphQL Playgroundにアクセスできます。

他の使い道としては、PostmanでGraphQLのqueryを書く時にも使えるようです。
https://learning.postman.com/docs/sending-requests/supported-api-frameworks/graphql/

難しいSchemaの取得方法

GraphQLのSchemaは、IntrospectionQueryを使うことで確認することが可能です。
しかし、全てのSchema定義を取得しようと思うと次のようなクエリをPOSTする必要があります。

curl https://api.github.com/graphql \
  -H 'Authorization: Bearer 7af842efa2f2c92676759f97dbeb4ef7d3635909' \
  -H 'content-type: application/json' \
  --data-binary '{"operationName":"IntrospectionQuery","variables":{},"query":"query IntrospectionQuery {\n  __schema {\n    queryType {\n      name\n    }\n    mutationType {\n      name\n    }\n    subscriptionType {\n      name\n    }\n    types {\n      ...FullType\n    }\n    directives {\n      name\n      description\n      locations\n      args {\n        ...InputValue\n      }\n    }\n  }\n}\n\nfragment FullType on __Type {\n  kind\n  name\n  description\n  fields(includeDeprecated: true) {\n    name\n    description\n    args {\n      ...InputValue\n    }\n    type {\n      ...TypeRef\n    }\n    isDeprecated\n    deprecationReason\n  }\n  inputFields {\n    ...InputValue\n  }\n  interfaces {\n    ...TypeRef\n  }\n  enumValues(includeDeprecated: true) {\n    name\n    description\n    isDeprecated\n    deprecationReason\n  }\n  possibleTypes {\n    ...TypeRef\n  }\n}\n\nfragment InputValue on __InputValue {\n  name\n  description\n  type {\n    ...TypeRef\n  }\n  defaultValue\n}\n\nfragment TypeRef on __Type {\n  kind\n  name\n  ofType {\n    kind\n    name\n    ofType {\n      kind\n      name\n      ofType {\n        kind\n        name\n        ofType {\n          kind\n          name\n          ofType {\n            kind\n            name\n            ofType {\n              kind\n              name\n              ofType {\n                kind\n                name\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n"}' \
  --compressed

スキーマを取得するのにこんなに長いクエリをいちいち書いてられないので、是非 get-graphql-schema を使ってみてください。

Discussion