【ITニュース解説】🚀Supercharging Docusaurus with MSW: Mock APIs for Live, Interactive Docs

APIやプロダクトの機能を説明するドキュメントを作成する際、バックエンドからのデータに依存する例をいかにリアルに見せるかは重要な課題となる。しかし、不安定なテスト環境に頼ったり、本番環境のAPIエンドポイントを直接公開したりするのはリスクが高い。このような状況で、ドキュメントの品質と安全性を同時に高める強力な手法が、MSW（Mock Service Worker）とDocusaurusの組み合わせである。

Docusaurusは、Reactをベースにした静的サイトジェネレーターで、技術ドキュメントサイトの構築によく用いられる。これにMSWを組み合わせることで、インタラクティブでリアルな動作をするドキュメントを実現できる。MSWは、Webブラウザの「Service Worker」という機能を利用して、ネットワークリクエストを傍受し、事前に定義されたモック（擬似的な）レスポンスを返すことができるツールである。このService Workerはブラウザのネットワーク層で動作するため、フロントエンドのコードは、本物のAPIとモックされたAPIのどちらと通信しているかを区別できないという特徴がある。これにより、開発者は実際のバックエンドがなくても、フロントエンドの機能開発やデモンストレーションを円滑に進められる。

ドキュメントにリアルなAPIレスポンスが必要な理由はいくつか存在する。まず、例示されたコードを実行した際に、常に期待通りのデータが返ってくることで、ドキュメントの内容と実際の動作の一貫性が保証される。これにより、読者は誤解なく学習を進めることができる。次に、安全なサンドボックス環境を提供できる点も大きい。読者は認証キーやVPN接続、複雑な初期設定なしに、コードサンプルを自由に試すことができ、実際にシステムを破壊する心配もない。これは、新しい技術やAPIを学ぶ上での大きな障壁を取り除く。さらに、モックAPIを使うことで、インターネット接続がないオフライン環境でもドキュメントの動作を確認できるため、開発者やコントリビューターが場所を選ばずに作業できるようになる。

MSWをDocusaurusプロジェクトに導入する手順は以下の通りだ。 まず、開発依存関係としてMSWをインストールする。これはnpm install msw --save-devというコマンドで実行できる。これにより、Service Workerを動かすための基本的なツールがプロジェクトに追加される。 次に、モックのアーキテクチャを設計する。主要な要素は「ハンドラー」と「ブラウザワーカー」だ。「ハンドラー」は、どのHTTPメソッド（GET, POSTなど）でどのURLにリクエストがあった場合に、どのようなレスポンスを返すかを定義する部分である。「ブラウザワーカー」は、MSWをブラウザで起動させるためのエントリーポイントとなる。推奨されるファイル構造としては、src/mocksフォルダの中にhandlers.js（エンドポイント定義）とbrowser.js（MSWのブートストラップ）を配置し、さらにDocusaurusのテーマをカスタマイズするためのsrc/theme/Root.jsでMSWを起動させる形だ。 実際のハンドラーの作成は、src/mocks/handlers.jsファイルで行う。例えば、rest.get('/api/info', ...)と記述することで、/api/infoへのGETリクエストに対して、どのようなステータスコードとJSONデータを含むレスポンスを返すかを定義できる。同様に、rest.post('/api/login', ...)でログインAPIのモックも作成できる。これにより、ログイン処理やデータ取得といった操作を、実際のバックエンドなしで再現できる。 ハンドラーを定義したら、次にsrc/mocks/browser.jsでこれらのハンドラーをまとめてService Workerとしてセットアップする。setupWorker関数にハンドラーのリストを渡すことで、Service Workerの準備が完了する。 最後に、Docusaurus内でService Workerを起動させる。Docusaurusでは、アプリケーション全体をラップするRoot.jsというファイルを通じて、開発モードの時にのみMSWを起動させることができる。src/theme/Root.jsにuseEffectフックを用いて、process.env.NODE_ENV === 'development'（つまり開発モードの場合）にworker.start()を呼び出すコードを記述する。この際、onUnhandledRequest: 'bypass'オプションを設定すると、モックされていないリクエストは通常通り実際のAPIに送信されるため、一部のAPIのみをモックしたい場合に便利だ。

これらの設定が完了すると、ドキュメント内にインタラクティブなコンポーネントを組み込めるようになる。例えば、Reactコンポーネント内でfetch('/api/info')を実行すると、MSWがこのリクエストを傍受し、定義されたモックレスポンスを返す。これにより、読者はドキュメント上でリアルタイムにAPIの動作とレスポンスデータを確認できる。

MSWを導入した後に、GitLab PagesのようなCI/CD環境でデプロイする際に、Service Workerのパスに関する課題に直面することがある。デフォルトでは、MSWはmockServiceWorker.jsというファイルをWebサイトのルートディレクトリ直下にあると想定するが、GitLab Pagesの動的なURL構造では、Service Workerの実際のパスが異なる場合がある。この問題を解決するには、worker.start()を呼び出す際にserviceWorker.urlオプションを使用し、Service Workerの正しいパスを動的に指定する。window.location.pathnameから現在のページのパスを取得し、それを基にmockServiceWorker.jsへの相対パスを構築することで、いかなるデプロイ環境でもMSWが正しく機能するようになる。

MSWを利用する上で、いくつかの一般的な落とし穴とその回避策も理解しておくべきだ。例えば、CORSエラーが発生した場合、モックするURLがfetchリクエストで指定しているURLと完全に一致しているか確認する必要がある。また、MSWのWorkerが起動しない場合は、Root.jsでbrowser.jsが正しくインポートされ、worker.start()が呼び出されているかを確認する。本番ビルドでMSWが意図せず動作することを防ぐため、NODE_ENVによる条件分岐で開発モードでのみ起動するようガードを設けることが重要だ。CI/CD環境での動的なパス問題は、前述のserviceWorker.urlオプションで解決できる。

MSWのさらに強力な側面は、これらのモック定義を開発環境だけでなく、アプリケーションのインテグレーションテストでも再利用できる点である。msw/nodeからsetupServerをインポートし、同じハンドラーを渡すことで、テストコードも本物のバックエンドに依存することなく、定義されたモックデータを使って動作させられる。これにより、開発環境、テスト環境、そしてドキュメントサイトという、複数の異なる文脈で一貫したAPIの振る舞いを保証できるようになる。

結論として、DocusaurusサイトにMSWを組み合わせてAPIをモックすることは、単なる装飾ではない。それはドキュメントをよりプロフェッショナルで、使いやすく、そして信頼性の高いものにするための重要な手段である。このアプローチにより、開発者は本番環境のような複雑な準備なしにリアルなAPIレスポンスを提供でき、ユーザーはより迅速に学習し、開発チームはドキュメント関連のトラブルシューティングに費やす時間を削減できる。