CI で楽して継続的に更新する GraphQL API ドキュメント

近年 GraphQL を使ったウェブ開発が増えてきているように感じます。

背景にアプリケーションのデータ管理として、複数のソースからデータを収集し、それらを加工してさまざまなプラットフォームへ提供したり、アプリケーションの UI に組み込んでリッチに表現するシーンが増えてきたことがあるでしょう。つまりそれぞれを担当する開発者間でアプリケーションの API 仕様を正しく認識する必要性が高まってきました。

スキーマファースト

GraphQL を採用することでスキーマを中心にコードを書くことが可能になります。スキーマはアプリケーションの設計図（もしくは仕様書）のような役割を持ちます。例えば query を用いるとどのようなデータを取得できるか、mutation を用いてどんなデータを操作できるのかを把握できます。

schema {
  query: Query
  mutation: Mutation
}

type Query {
  "Return the hero by **episode**."
  hero(episode: Episode): Character
}

type Mutation {
  "Save the `favorite` episode."
  favorite(episode: Episode!): Episode
}

スキーマを基に graphql-codegen や gqlgen といったツールを使うことで、それぞれのプログラミング言語に合わせたコードを自動生成することもできます。つまりスキーマを先に決めて、バックエンド、フロントエンドそれぞれの開発者に共有し、互いにその仕様を満たすような機能を実装することができます。

CI で楽して継続的に更新する API ドキュメント

前節ではスキーマがアプリケーションの設計図（もしくは仕様書）のような役割を持つと説明しました。しかし、スキーマの中身が大きくなってきたときに人間が読みやすい API ドキュメントにはならないと思います。そこで、コードを自動生成するのと同じ要領で、スキーマから人間が読みやすい API ドキュメントを生成したいニーズが生まれるはずです。

このニーズを想定してか、GraphQL の 3.3 Descriptions^[1] では Markdown の文法 (CommonMark) が扱えるように仕様が定まっています。

GraphQL にもスキーマを基に API ドキュメントを生成するジェネレータが存在します。

また API ドキュメントジェネレータを CI 上で動かすことでスキーマの更新とともに API ドキュメントも継続的に更新できるメリットがあります。具体的には次の手法が考えられます。

1. API ドキュメントジェネレータを実行してスキーマから API ドキュメントを生成する
2. プロジェクトに含む API ドキュメントと生成された API ドキュメントに差分があれば commit & push する^[2]

GraphQL API ドキュメントジェネレータの紹介

ここでいくつか GraphQL API ドキュメントジェネレータを紹介します。どれもメリット、デメリットがあるでしょう。（他にもあれば教えてください）

mvochoa/graphqldoc

• Go を使ってインストールできる
  • README に GitHub Releases でもバイナリを提供しているような記述があったが見つからなかった
• introspection をサポートした GraphQL エンドポイントへリクエストを行った結果を使い markdown ドキュメントを生成する
• 現在リポジトリは Archive されており開発が停止してる

2fd/graphdoc

• npm を使ってインストール
• 静的ページ (html) を生成し、シンタックスハイライトされた状態でそれぞれの type 毎にスキーマを表示
• 静的ページ上では、検索がサポートされていて、type を絞り込める
• 前節のように introspection やスキーマを直接読み込んで生成できる
• セットアップコストが高いが見やすい
  • パーマリンクを使った共有には html をホスティングする必要がある
• Descriptions などいくつかの文法をサポートしていない

Code-Hex/gqldoc

筆者は 2fd/graphdoc を愛用していましたが、静的ページをホスティングしたり CI 上でドキュメントを生成するためのタスクを作成したりで導入にかなり手間をかけました。手間をかけたのにも関わらず、いくつかの文法をサポートしてない事を知った時はとてもショックを受けました。

そこから簡単に導入でき、スキーマの変更と共に API ドキュメントも継続的に更新できるジェネレーターがあると嬉しいなといったモチベーションでこのツールを作成しました。

• GitHub Releases や Homebrew, Go を使ってインストールできる
• GitHub の GraphQL API Reference に似た形式で Markdown を生成する
• introspection やスキーマを直接読み込んで生成できる
• 2021-03-31 現在の文法には対応しているので Descriptions に記述した Markdown も反映される
• Markdown で出力されるため、GitHub や VSCode などを使っていればリッチに表示できる
  • パーマリンクを使った共有も簡単
  • 静的ページ (html) へ変換することもできる
• 生成した API ドキュメントに差分があれば commit & push してくれる GitHub Actions も提供している
  • スキーマが更新されると API ドキュメントも楽して継続的に更新できる
• 公開したばかりなので、Subscription をサポートしていないなど、提供できてない機能もいくつかある。^[3]

まとめ

GraphQL を採用することでバックエンド、フロントエンドなど分野に関係なく、スキーマファーストなアプリケーション開発ができます。それぞれを担当する開発者間で API の仕様を認識するためにスキーマを共有できますが、量が増えてくると可読性に問題が出てきます。そこでいくつかのドキュメントジェネレータを紹介しました。

GraphQL を使ったスキーマファーストな開発を採用することで、コードを自動生成するのと同じように API ドキュメントも自動生成できます。更に CI/CD を用いて継続的に自動でドキュメントを生成するようにすれば、ドキュメントが古いといった問題も解消されるので、ぜひ検討してみてはいかがでしょうか。