patorashのブログ

方向性はまだない

GraphQLのスキーマ情報からドキュメントを生成する

漠然と考えていたことが既に書かれていたので、非常に参考になったし面白かった。

developer.kaizenplatform.com

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に変わっていた。

graphidocsorg.github.io

以下で、グローバル環境にインストールできる。

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。