はじめに
GraphQL開発初心者のバックエンドエンジニアです。
Restで開発していた時は、SwaggerでAPIドキュメントを作成していました。
GraphQLを使用開始してからスキーマファイルを見る時、ファイルを直接見ており、やりづらさを感じていました。
そこでスキーマファイルをドキュメント化できないかと色々調べてみましたので、アウトプットしていきたいと思います。
本投稿が初のため、読みづらさあると思いますが、よろしくお願いします。
概要
- GraphQLのスキーマファイルからドキュメントを作成して、スキーマを見やすくしたい。
- ドキュメント化して可読性を上げることで開発生産性を向上させたい。
前提
- GraphQLを使用した開発経験は1年未満。
- 現在の開発現場ではGitHubを使用している。
- 手動でのドキュメント修正はしたくない。（メンテしなくなるため）
調べてわかったこと
- GitHubActionsを使用して、スキーマファイルに修正があったらドキュメント自動生成するのが良さそう。
- こうすればドキュメントは意識せずに、開発時はスキーマファイルだけ修正すればいい。
- ドキュメント化にはHTML形式 or MarkDown形式で出力できる2パターンがある。
- △：HTML形式→GitHubPagesで公開して生成したHTMLを見るイメージ
- ○：MarkDown形式→普通にGitHub上で見れる（基本はGitHub上で見るためこちらがBetter）
ドキュメントツールの比較
※.調べたら色々ありましたがシェア高そうなのを載せてあります
| ツール | HTML or MarkDown | メリット | デメリット | example |
|---|---|---|---|---|
| SpectaQL | HTML | シェア高そうで、参照できる記事が一番多い。 (少し前GraphQlのセミナーに参加した時、発表者もこれ使ってるって言ってた) | 導入するとしたらGitHubPagesで公開してみることになりそうだが、別ページに行くのも面倒で見なくなりそう | https://hibohiboo.github.io/kartagraph/publish/graphql-schema/#group-Operations-Queries |
| Code-Hex/gqldoc | MarkDown | MarkDownなのでGitHub上でソースを見ればドキュメントが見れる。 GitHubActionsのワークフローが準備されている。 | - | https://github.com/Code-Hex/gqldoc/blob/main/example/starwars/README.md |
| graphql-markdown | MarkDown | ・MarkDownなのでGitHub上でソースを見ればドキュメントが見れる | (これというデメリットではないが、、) GitHubActionsのワークフローは準備されていない | https://github.com/wheatandcat/PeperomiaBackend/blob/master/schema.md |
HTML形式で出力するツールはSpectaQL以外にも結構あったが、
基本的にどれも同じかと思ったため割愛。
(2fd/graphdocなどあったが、SpectaQL と大体同じ)
検討結果
Code-Hex/gqldocを採用
- ドキュメント化するとQuery,Mutations,Objects,Enums,Unions,Input objects,Scalarsごとにファイル作成されるが、現状問題なし。
- GitHubActionsのワークフローを利用して、スキーマ修正のPushがあったらドキュメントが自動生成されるようにGitHubActionsを設定。
おまけ
調べてたらこんなドキュメントツールもありました。スキーマがネストとして複雑になってきたら便利だと思いました。
https://graphql-kit.com/graphql-voyager/
最後に
自動化は実施すればチーム全体の生産性が向上させることができるため、とても有用だと思いました。
これからもドキュメント化に限らず、ほかの手動作業についても自動化されることができるようにしていきたいです。
読んでいただいた方、ありがとうございました。