漠然と考えていたことが既に書かれていたので、非常に参考になったし面白かった。
GraphQL APIの設計を中心にフロントエンド、バックエンドをそれぞれ作っていくと、それぞれの実装待ちが発生しなくてよい。しかもAPI仕様のドキュメントを作成することも簡単だった。
graphql-rubyからGraphQLのスキーマ情報を作成する
Railsプロジェクトでgraphql-rubyを使ってスキーマ情報を生成するのは簡単。Rakefileに以下を追記して、rake taskを追加する。
#!/usr/bin/env rake require File.expand_path('../config/application', __FILE__) require 'graphql/rake_task' # 追加 Rails.application.load_tasks GraphQL::RakeTask.new(schema_name: 'SampleSchema') # 追加
確認してみる。
$ bin/rake -T | grep graphql rake graphql:pro:validate[gem_version] # Get the checksum of a graphql-pro version and compare it to published versions on GitHub and graphql-ruby.org rake graphql:schema:dump # Dump the schema to JSON and IDL rake graphql:schema:idl # Dump the schema to IDL in ./schema.graphql rake graphql:schema:json # Dump the schema to JSON in ./schema.json
rake graphql:schema:dumpで、schema.graphqlとschema.jsonを生成してくれるようになった。
ドキュメントHTMLの生成
ドキュメントHTMLの生成も簡単だけれど、実は結構ハマった。
さきほどの参考記事では、graphdocが紹介されていて、最初はそれを使おうとしたのだけれど、schema.graphqlからドキュメントを作成するときにエラーになった。どうもコメントに対応できていないらしい…。また、リポジトリが1年以上メンテされてないみたいでこれ大丈夫か？？？と思っていた。 すると、どうもgraphidocsにフォークしてメンテナンスされているらしい。そのため、npmパッケージの名前もgraphdocからgraphidocsに変わっていた。
以下で、グローバル環境にインストールできる。
npm install -g @graphidocs/docs
しかし、node-gyp rebuildが走ってエラーが出ていた（ただ、インストール自体は成功していた…）。 解決方法がわからなかったので（Nodeを6系までダウングレードすれば通る、みたいなのはあったが、今は10系を使っているから嫌だった）、エラーメッセージは放置した。
ただ、プロジェクトのドキュメントを作るのにグローバルにインストールしたくないなぁと思って、そこは変更した。
$ yarn add @graphidocs/docs --dev
エンドポイントからドキュメントを作る
既にGraphQLのAPIがあるのであれば、そこをエンドポイントして指定して実行すれば、生成してくれる。ローカルでやるのであれば、bin/rails sをした状態で、以下を実行する
$ yarn run graphidocs -e http://localhost:3000/graphql -o ./doc/schema
毎回オプションをつけるのは大変なので、package.jsonにオプションを設定しておくことも可能。
{ "dependencies": { # 省略 }, "devDependencies": { "@graphidocs/docs": "^1.0.4" }, "graphidocs": { "endpoint": "http://localhost:3000/graphql", "output": "./doc/schema" } }
こうすると、以下でOK。
$ yarn run graphidocs
スキーマからドキュメントを作る
しかし、エンドポイントからドキュメントを作るのでは、さきほどの参考記事のようにフロントエンド、バックエンドでAPI仕様を議論しながらは進められない。必ずバックエンドの実装後になってしまうので、やはりスキーマ情報からドキュメントを作りたい。
スキーマ情報からドキュメントを作るには、オプションを変更する。既にある程度API実装があるのであれば、先ほど追加したrake taskを実行して、スキーマ情報をダンプしておく。
$ bin/rake graphql:schema:dump # schema.graphqlとschema.jsonを生成 $ yarn run graphidocs -schema ./schema.graphql -o ./doc/schema
ここでは、schema.graphqlを指定したが、schema.jsonでも動く。
こちらも毎回オプションをつけるのは大変なので、package.jsonにオプションを設定できる。
{ "dependencies": { # 省略 }, "devDependencies": { "@graphidocs/docs": "^1.0.4" }, "graphidocs": { "schemaFile": "./schema.graphql", "output": "./doc/schema" } }
こうすると、以下でOK。
$ yarn run graphidocs
これで、schema.graphqlを介してフロントエンド、バックエンドの人で意見交換して、ドキュメントを生成してそれぞれが開発する土台ができたかなと思う。
GraphQLのドキュメントを見るためのWebサーバを定義する
ドキュメントは./doc/schema配下にできたものの、そこを開きにいくのも面倒なので、WEBrickでWebサーバを作った。
プロジェクトのルートフォルダにgraphidocs.rbを作成した。
# graphidocsで生成したgraphqlのスキーマ情報を見るためのサーバを立ち上げます。 # ./doc/schemaが存在しないか古い場合、まず`yarn run graphidocs`を実行してください。 # その後、`ruby graphidocs.rb`を実行してください。 require 'webrick' include WEBrick server = HTTPServer.new( DocumentRoot: './doc/schema', BindAddress: '0.0.0.0', Port: 8000 ) %w(INT TERM).each do |sig| trap(sig) { server.shutdown } end server.start
これを実行する。
$ ruby graphidocs.rb [2019-04-03 10:53:47] INFO WEBrick 1.4.2 [2019-04-03 10:53:47] INFO ruby 2.5.5 (2019-03-15) [x86_64-darwin16] [2019-04-03 10:53:47] INFO WEBrick::HTTPServer#start: pid=4858 port=8000
http://localhost:8000 にアクセスすると、GraphQLのドキュメントが読めるようになった。サーバの終了はCtrl + CでOK。
