GraphQL スキーマから API ドキュメントを自動生成して GitHub Pages へデプロイする

Classi で提供している学習トレーニング機能を裏で支えているコンテンツ管理システム ( 以下、内部 CMS ) では、バックエンドに GraphQL を採用しています。 この GraphQL は Classi 内の様々なシステムで広く利用されています。

tech.classi.jp

内部 CMS の開発チームでは、この GraphQL スキーマの API ドキュメントを自動生成して GitHub Pages でホスティングしています。
GitHub Pages は GitHub Actions ワークフローを作成するだけで簡単に静的サイトをデプロイすることができます。また、 Classi では GitHub Enterprise Cloud を利用しており GitHub Pages のアクセス範囲を制限することもできるため、社内向けドキュメントも安全にホスティングすることが可能です。

docs.github.com

GitHub Pages でホスティングすることで社内メンバーはいつでも簡単に API ドキュメントを参照できるため、チーム内外を問わず GraphQL スキーマに基づいた議論やコミュニケーションを円滑にする上で非常に役に立っています。

API ドキュメントの自動生成には Magidoc を使用しています。

この記事では Magidoc を利用して GraphQL スキーマから API ドキュメントを自動生成し、生成したドキュメントを GitHub Pages でホスティングする方法を紹介します。

Magidoc について

Magidoc は GraphQL スキーマから API ドキュメントを自動生成するためのツールです。API ドキュメントは HTML 形式で生成されます。

• リポジトリ : magidoc-org/magidoc
• 公式サイト : magidoc.js.org

実際にどのようなドキュメントが生成されるのかは以下のサイトで確認できます。

• magidoc-carbon-multi-page.netlify.app/queries/capsule

Magidoc の使い方

1. インストール

Magidoc CLI は npm パッケージとして提供されているため、 npm コマンドでインストールできます。

• @magidoc/cli

# グローバルにインストールするコマンド例
$ npm install -g @magidoc/cli@latest

インストールが完了すると magidoc コマンドが実行できるようになります。

$ magidoc --help
Usage: Magidoc [options] [command]

Magidoc CLI helps you build beautiful and fully customizable GraphQL static documentation websites in seconds.

Options:
  -V, --version       output the version number
  -h, --help          display help for command

Commands:
  generate [options]  Generates a full static website using a template. Using this command gives you access to a limited
                      range of customization. If you wish to customize the website further than what is available, use the
                      eject command.
  preview [options]   Preview the documentation website generated with the generate `generate` command.
  dev [options]       Starts a development server with hot-reload as changes occur to watched files.
  eject [options]     Ejects from Magidoc basic template configuration, to allow for full customization of the template.
                      This will initialize a folder from a template of your choice, which can then be modified however you
                      wish.
  help [command]      display help for command

もちろん npx コマンドで実行することもできます。

$ npx @magidoc/cli@latest --help

2. 設定ファイルを作成する

Magidoc の設定は magidoc.mjs というファイルに記述します。

// magidoc.mjs
export default {
  introspection: {
    type: "sdl", // スキーマをファイルから読み込む場合は "sdl" を指定する
    paths: ["schemas/**/*.graphqls"], // スキーマファイルのパスを指定する
  },
  website: {
    // テンプレートを指定する
    // v6.1.0 時点でデフォルトで用意されてるのは "carbon-multi-page" のみ
    template: "carbon-multi-page",

    // Web サイトのルートパスを指定する
    // Public な GitHub Pages の URL は https://<オーナー名>.github.io/<リポジトリ名>/ のようになるので、
    // ここには "/<リポジトリ名>" を指定する必要がある
    siteRoot: "/example-repository",
  },
};

他にも様々な設定が用意されています。以下はその一例です。

• URL から GraphQL スキーマを読み込む
• 設定ファイルに直接 GraphQL スキーマを記述する
• カスタムページを追加する
• etc.

詳細については公式ドキュメントをご参照ください。

magidoc.js.org

3. API ドキュメントを生成する

magidoc generate コマンドで API ドキュメントを生成することができます。

$ magidoc generate
# npx を使用する場合
$ npx @magidoc/cli@latest generate

生成されたドキュメントは ./docs/ ディレクトリに出力されます。 ( 出力先は設定ファイルで変更可能 )

docs/
├─ index.html
├─ _app/
│  └─ ...
├─ introduction/
│  └─ ...
├─ mutations/
│  └─ ...
├─ queries/
│  └─ ...
└─ types/
   └─ ...

生成されたドキュメントをローカルで確認するには magidoc preview コマンドを実行します。サーバーが起動し、 http://localhost:4000 からドキュメントを閲覧することができます。

$ magidoc preview
# npx を使用する場合
$ npx @magidoc/cli@latest preview

localhost:4000

生成したドキュメントを GitHub Pages にデプロイする

GitHub Pages にデプロイするには以下の 2 通りの方法がありますが、今回は GitHub Actions からデプロイする方法を紹介します。

• ブランチからデプロイする
• GitHub Actions からデプロイする ← 今回紹介するのはこちら

それぞれの方法の詳細については公式ドキュメントをご参照ください。

docs.github.com

1. GitHub リポジトリの設定

GitHub リポジトリの Settings をクリックして設定画面に遷移します。

左サイドメニューから Pages をクリックして、 Source を GitHub Actions に設定します。

2. GitHub Actions ワークフローを作成する

GitHub Actions から GitHub Pages をデプロイするには以下の 2 つのアクションを利用します。

• actions/upload-pages-artifact
  • GitHub Pages にデプロイするファイルをアップロードするアクション
• actions/deploy-pages
  • アップロードしたファイルを GitHub Pages にデプロイするアクション

ワークフローは以下のようになります。この例では、 main ブランチに変更が push されるたびに GraphQL API ドキュメントを生成して GitHub Pages にデプロイします。

name: Publish API Docs

on:
  push:
    branches:
      - main

jobs:
  publish-api-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      # actions/deploy-pages に必要な権限
      # 参考: https://github.com/actions/deploy-pages#security-considerations
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      # setup
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      # build
      - run: npx @magidoc/cli@latest generate

      # publish
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs
      - uses: actions/deploy-pages@v4
        id: deployment

GitHub Pages へのデプロイが完了すると https://<OWNER>.github.io/<REPOSITORY> から API ドキュメントを閲覧できるようになります。

---

冒頭で紹介した内部 CMS の GraphQL API ドキュメントのデプロイでは、実際には以下のようなワークフローを作成しています。内部 CMS の GraphQL スキーマのリリースには googleapis/release-please-action を利用しているので、 release_created output を参照することで「新しいバージョンがリリースされるたびに API ドキュメントを更新する」ということを実現しています。

tech.classi.jp

name: Release Please

on:
  push:
    branches:
      - main

jobs:
  release-please:
    runs-on: ubuntu-latest
    outputs:
      release_created: ${{ steps.release-please.outputs.release_created }}
    steps:
      # ...省略
      - uses: googleapis/release-please-action@v4
        id: release-please
        with:
          release-type: node

  publish-api-docs:
    needs:
      - release-please
    # 新しいリリースが作成されたときに API ドキュメントを更新する
    if: ${{ needs.release-please.outputs.release_created == 'true' }}
    # ...省略

まとめ

リッチな API ドキュメントがあるとテンションが上がります。
よりイケてるドキュメントにするために設計や説明文もしっかり書こうという気持ちになりますね。モチベーション大事。