APIモッキングとは？モックサーバーの方式選定と契約ドリフト対策を実装目線で解説

APIモッキングとは、実際のAPIの代わりに決められた応答を返す偽のエンドポイントを用意し、呼び出し側の開発とテストを先に進められるようにする手法です。バックエンドが未完成でも画面を作れる、外部SaaSの回数制限を気にせずテストを回せる、といった効果がありますが、雑に入れると「モックでは通るのに本番で落ちる」という別の事故を招きます。この記事では、APIモッキングの定義と単体テストのモックとの責務の違いから、実装方式ごとの動作原理、Prism・MSW・WireMockといったツールの選定基準、OpenAPIを起点にモックサーバーを立てる手順、そしてモックと本番APIがずれる契約ドリフトの検知方法と、あえて見送るべき場面までを実装者向けに整理します。

まとめ｜APIモッキングの採用条件とモックサーバー方式の選び分け

APIモッキングが効くのは、呼び出し側と提供側の作業が時間的にずれているときです。フロントエンドがバックエンドの完成を待つ、決済や外部連携のサンドボックスが不安定でテストが詰まる、障害時の応答を再現したいのに本物のAPIでは異常系を作れない。この3つが典型的な導入理由で、いずれも「待ち時間」か「再現不能な状態」を金銭ではなく仕組みで解決する話に還元されます。

方式は、OpenAPI文書からモックを生成する型、クライアント側で通信を横取りする型、独立したモックサーバーを立てる型に分かれます。仕様書が既にあるならOpenAPI起点が最も安全で、フロントエンドの単体・結合テストだけならクライアント横取り型が軽く済み、異常系や遅延の注入まで踏み込むなら独立サーバー型を選びます。

そして最大の落とし穴が契約ドリフトです。モックを手書きで作った瞬間から、本番APIの仕様変更に追随できず乖離が始まります。防ぐ現実解は、モックの定義をOpenAPIなどのスキーマと同じ情報源から生成し、契約テストで提供側を継続検証することに尽きます。スキーマを整備しないままモックだけ導入するのは、後で回収できない負債を積む選択です。

APIモッキングの定義と単体テストのモック（テストダブル）との責務境界

APIモッキングという言葉は、単体テストで使う「モックオブジェクト」と混同されがちです。両者は目的も置かれる層も異なり、ここを取り違えると「単体テストで足りるのにモックサーバーを立てる」といった過剰な構成になります。まず境界を引きます。

APIモッキングの定義：ネットワーク層で本物のAPI応答を代替する仕組み

APIモッキングは、HTTPやgRPCといった通信のレベルで、本物のAPIが返すはずの応答を代わりに返す仕組みを指します。呼び出し側のコードには手を入れず、接続先のURLだけをモックに向ける、あるいは通信そのものを横取りする形で成立させるのが基本形です。通信の相手が入れ替わっただけなので、シリアライズ、ステータスコードの分岐、タイムアウト処理といった実装はそのまま検証対象に残ります。この「実装を差し替えずに相手だけ差し替える」性質が、単体テストのモックとの決定的な違いです。

単体テストのモックとの違い：差し替える層と検証したい対象の分岐

単体テストで使うモックは、対象クラスが依存するオブジェクトをプロセス内で偽物に置き換えます。通信は発生せず、検証したいのは呼び出し側のロジックそのものです。テストダブルの5分類やスタブとの使い分けはモックとは？スタブとの違い・テストダブル5分類と単体テストでの使い分けを実装者向けに解説で整理していますので、単体テスト側の設計はそちらを参照してください。対してAPIモッキングはプロセスの外にモックを置き、HTTPクライアントの設定、ヘッダの付与、リトライ、JSONのパースまで通します。判断の目安はこうです。検証したいのがビジネスロジックなら単体テストのモック、通信を含む結合の挙動なら、APIモッキングを選びます。

モック・スタブ・サンドボックスの区別と実務での基本的な呼び分け方針

現場では3つの言葉が混在するのが実情です。スタブは決め打ちの応答を返すだけの単純な代替、モックは呼ばれ方（回数や引数）まで検証する代替、サンドボックスは外部サービス提供元が用意した本物に近い検証環境を指します。API開発の文脈では厳密な区別より、次の実務的な優先順位のほうが役に立ちます。

• 提供元が公式サンドボックスを出しているなら、まずそれを使う（仕様のずれが起きない）
• サンドボックスが無い、または不安定なら自前のモックサーバーを立てる
• 異常系や特定の応答パターンだけ再現したいなら、モックで該当ケースだけを上書きする

StripeやSalesforceのように成熟したサンドボックスがある場合、自前モックはかえって精度を落とします。自前モックは「提供側が用意していない状況を作る道具」と位置づけてください。

モックサーバー実装方式ごとの動作原理と開発フェーズ別の適用範囲

APIモッキングの実装方式は、通信のどこに割り込むかで分かれます。方式ごとに立ち上げコスト、再現できる範囲、CIへの組み込みやすさが違うため、フェーズに合わせて選び分けます。

OpenAPI駆動型：仕様書からモック応答を生成する方式の動作と限界

OpenAPI文書を読み込み、定義されたパスとスキーマからモックサーバーを自動起動する方式です。Stoplight Prism（CLIは5.16系／2026-08-08時点のnpm実測）が代表格で、prism mock openapi.yaml のようにコマンド一つでポートが開く。応答は仕様書のexampleをそのまま返すほか、動的モードにすればスキーマ定義から値を毎回生成できます。Prefer ヘッダでステータスコードや返す例を切り替えられるため、404や500の分岐確認も仕様書の範囲で行えます。限界は明確で、仕様書に書かれていない挙動は再現できません。「POSTで作ったリソースが直後のGETで取得できる」といった状態を持つ振る舞いは、この方式では扱えない領域です。

クライアント横取り型：Service Workerとインターセプタによる通信の差し替え

アプリケーションのプロセス内で通信を横取りし、サーバーを立てずにモック応答を返す方式です。MSW（Mock Service Worker／2.15系）が代表で、ブラウザではService Workerがfetchとリクエストを捕捉し、Node.js側ではHTTPモジュールへのインターセプタが同じハンドラ定義を再利用します。同じモック定義を開発サーバーとテストの両方で使い回せるため、フロントエンド主導のプロジェクトでは維持コストが最も低くなります。逆に、モックがアプリのコードベースに同居するので、別チームのバックエンドやモバイルアプリからは呼べません。適用範囲はフロントエンド開発と、そのコンポーネント・結合テストまでです。

スタンドアロンサーバー型：遅延・障害注入まで再現する独立プロセス方式

モック専用のプロセスを立て、ルールに基づいて応答を返す方式です。JVM系ではWireMock（3.13系）、GUIとCLIを併せ持つ製品ではMockoon（CLIは9.8系）が使われます。この方式の価値が表れるのは正常系ではなく異常系です。固定遅延やランダム遅延の付与、接続のリセットや不正なレスポンスの返却といった障害注入ができるため、リトライ設計やサーキットブレーカーが本当に動くかを検証できます。手軽さを優先するならjson-serverもありますが、2026-08-08時点でnpmの最新版は1.0.0-beta系にとどまり正式版に達していないため、恒久的なCI基盤に据えるのは避けるのが無難です。

主要APIモックツールの比較軸とプロジェクト規模別の選定基準

ツール選びで見るべき軸は多くありません。仕様書との連動、状態の保持、障害注入、CIでの起動しやすさ、この4つでほぼ決まります。バージョンは2026-08-08時点でnpm registryとGitHub Releases APIから取得した実測値です。

Prism・MSW・WireMock・Mockoonの機能比較と得意領域の違い

表の読み方はこうです。仕様書が整っているならPrism、画面側だけで完結するならMSW、テストで壊れ方を作りたいならWireMock、GUIで誰でも編集したいならMockoonという対応になります。1つに絞る必要はなく、フロントはMSW、CIの結合テストはWireMockという併用は珍しくありません。

状態を持つモックが必要かどうかで変わる選定の分岐点となる基準

選定を最初に分けるのは状態の有無です。ログイン後に取得したトークンを次のリクエストで使う、作成したリソースの一覧が増える、といった連続した操作を検証するなら、リクエスト間で状態を保持できる方式が要ります。WireMockのシナリオ機能やMockoonのデータバケットはこの用途に応え、MSWもハンドラ内で変数を持てば擬似的に再現できます。一方でPrismのような仕様書駆動型は、原則としてリクエストごとに独立した応答を返す。画面遷移を伴うシナリオテストをPrismで押し通そうとして詰まる例は多く、この一点だけで方式を変える判断は妥当です。

CI組み込みの容易さとチーム外共有の可否から絞る実務判断基準

CIでの扱いやすさは、Dockerイメージの有無とCLIの起動速度で決まります。WireMockとMockoonは公式イメージがあり、テストジョブの前段でコンテナを起動して終了時に破棄する形が組めます。Prismもnpxで即起動できるため、OpenAPI文書をリポジトリに置いていれば追加の資材はほぼ不要です。判断の分かれ目はチーム外共有にあります。モバイルアプリの開発チームや協力会社が同じモックを叩く必要があるなら、クライアント横取り型は選べません。この場合はスタンドアロン型を共有環境に置く構成になりますが、後述する契約ドリフトのリスクが跳ね上がる点は覚悟が要ります。

OpenAPI起点でモックサーバーを立てる実装手順と並行開発への組み込み

手順そのものは短時間で終わります。難しいのは手順ではなく、モックを何から生成するかという設計判断のほうです。ここではOpenAPI文書を単一の情報源に据えた進め方を示します。

スキーマを単一の情報源に据える準備とexample定義の粒度

最初にやるのは、モックを書くことではなくOpenAPI文書を整えることです。パスとメソッド、リクエストボディ、レスポンススキーマ、そして各レスポンスのexampleを埋めます。この考え方はスキーマファーストとは？OpenAPI起点の並行開発と破壊的変更検知を解説で扱う設計手順と同じ土台に立ちます。exampleの粒度は、正常系1件に加えて、空配列・最大件数・エラー応答の3パターンを最低限そろえてください。空配列を用意しておかないと、フロントエンドが「データが0件のときの表示」を作り忘れる事故が起きます。スキーマの記述精度そのものについてはJSON Schemaとは？JSONの構造を検証する書き方とDraft 2020-12の実装を実装者目線で解説【2026年版】の型定義の考え方が土台になります。

モックサーバーの起動から応答パターン切り替えまでの実装手順例

OpenAPI文書が用意できたら、次の順で進めます。

1. リポジトリに openapi.yaml を配置し、CIでスキーマの構文検証を通す
2. Prismを prism mock -p 4010 openapi.yaml の形で起動し、ポートを固定する
3. 呼び出し側の接続先を環境変数で切り替えられるようにし、開発時のみモックへ向ける
4. 異常系の確認は Prefer: code=500 のようにヘッダで応答を切り替える
5. docker composeにモックを1サービスとして追加し、起動手順をコマンド1つに畳む

3番目を省略して接続先をコードに直書きすると、モックを外す作業が後で膨れます。環境変数での切り替えは最初に入れてください。

フロントエンドとバックエンドの並行開発に組み込む工程設計手順

並行開発の効果は工程の切り方で決まります。仕様書の合意を1つのマイルストーンとして独立させ、その日を境にフロントとバックが同時に走り出す形にすると、待ち時間が実質ゼロになります。仕様書を書きながら実装も進める運びにすると、モックの作り直しが常時発生して効果が消えてしまう。受託開発では、この工程設計が見積りの前提そのものを左右します。API設計と連携実装をまとめて任せられる体制を検討するなら、API開発・システム連携の支援内容が判断材料になります。

モックと本番APIがずれる契約ドリフトの発生条件と検知の仕組み

APIモッキングで最も損失が大きい失敗が、モックと本番の乖離です。テストは全て緑なのに結合した瞬間に落ちる、という状況はほぼ全てここに起因します。競合記事がまず触れない論点なので、発生条件と検知手段を具体的に押さえます。

契約ドリフトが起きる3つの発生条件と典型的な症状を見分ける基準

乖離は決まった条件で起きます。第一に、モック定義を手書きし、スキーマと別管理にしたとき。第二に、共有モックサーバーを長期間置きっぱなしにし、更新責任者を決めなかったとき。第三に、提供側がフィールド名や型を変えたのに、呼び出し側のテストが本物のAPIに一度も触れていないときです。症状は共通しています。結合テストや受入テストの初日に、nullを想定していないフィールドがnullで返る、日付形式が違う、配列だと思っていた項目がオブジェクトになっている、といった型レベルの不整合が一斉に噴き出します。

契約テストとスキーマ検証を組み合わせたドリフト検知の実装手順

検知は2段構えにします。1段目はスキーマ検証。モックをOpenAPIから生成し、同じOpenAPIで本番APIの応答も検証すれば、両者が同じ定義に縛られます。Prismにはリクエストを実APIへ転送しつつ仕様との差分を報告する動作モードがあり、検証環境に挟むと乖離を早期に拾えます。2段目が契約テストです。呼び出し側が期待する契約をファイル化し、提供側のCIで検証させる仕組みは契約テストとは？Pactによる消費者駆動契約の実装とCI組み込みを実装者向けに解説で詳述しています。Pact JS（17.1系）なら、消費者テストが生成した契約ファイルを提供側のパイプラインで検証させる構成が基本形になります。

モックを廃棄するタイミングと本物のAPIへ切り替える判断基準

モックは永続資産ではありません。廃棄の判断基準を先に決めておくと、ドリフトの温床を作らずに済みます。目安は明快で、本物のAPIが開発環境から安定して叩けるようになった時点で結合テスト以降のモック利用を止める。単体テストと画面のコンポーネントテストではモックを残してよく、結合・E2E・受入の3層は本物へ切り替えます。切り替えを先送りするほど、本番で初めて発覚する不整合の量が増えていきます。

APIモッキングを見送るべき場面と投資が回収できない失敗パターン

導入を勧める記事は多い一方、やめるべき条件を書いた記事はほとんどありません。ここでは条件を付けて言い切ります。

モックを入れないほうが速い3つの条件と判断の根拠を見極める基準

次の条件に当てはまるなら、APIモッキングは導入しないでください。

• 提供側APIが既に開発環境で安定稼働しており、呼び出し側から直接叩ける。モックは二重メンテのコストしか生みません
• 提供元が公式サンドボックスを提供している。自前モックは仕様の追随が遅れ、精度で必ず負けます
• APIの仕様がまだ流動的で、週単位で項目が変わっている。この段階でモックを作ると、作り直しの工数が並行開発の短縮分を上回ります

3番目は特に見落とされます。モックの価値は「仕様が固まっていて実装だけが遅れている」状態で最大化されるものであり、仕様が固まっていない段階では、モックではなく仕様合意そのものに時間を投じるほうが早く終わります。

結合テスト以降でモックに依存し続ける構成が招く検出漏れの原因

最も高くつく失敗が、テストの上位層までモックで固めてしまう構成です。E2Eテストの接続先がモックのままだと、認証トークンの有効期限、ページングの境界、同時実行時の競合といった本番固有の問題を検出できません。各層に何を割り当てるかはテストピラミッドとは？単体・結合・E2Eの配分と実装者向けテスト戦略設計の考え方に沿って決めてください。E2Eでモックを使ってよいのは、決済の本番課金など実行そのものに副作用がある処理に限られます。

共有モック環境の放置とバージョン固定漏れによる運用事故の原因

チーム共有のモックサーバーを立てたまま誰も更新しない構成も事故につながります。ありがちな経緯はこうです。プロジェクト初期に共有モックを立て、フロントとモバイルの両チームがそこへ向く。数か月後に提供側APIが更新されるが、共有モックの定義は初期のまま。両チームは古い仕様に合わせて作り込み、統合フェーズで大量の手戻りが出る。対策は3点。共有モックの定義をアプリのリポジトリと同じ場所で管理する、CIでOpenAPIから再生成して自動反映する、モックツールの版をロックファイルで固定して挙動の差異を防ぐ。3点目は、マイナー更新で応答の既定値が変わった際の切り分けを助けます。

よくある質問集｜APIモッキングの実装と運用で迷いやすい論点

APIモッキングの導入時に実務で繰り返し出てくる質問を、判断に使える形で答えます。

APIモックとスタブは何が違うのですか？

スタブは決め打ちの応答を返すだけで、呼ばれ方は検証しません。モックは応答に加えて、何回どんな引数で呼ばれたかを検証対象にできます。実務では、呼び出し回数やヘッダの内容を確認したいならモック機能を持つツール、応答さえ返ればよいならスタブ相当の設定で足ります。

モックサーバーは無料で作れますか？

作れます。Stoplight Prism、MSW、WireMock、Mockoonはいずれもオープンソースとして公開されており、ローカル起動やCI利用に費用はかかりません。費用が発生するのは、クラウド上のホスティング型サービスとしてモックを常時公開する場合や、チーム向けの管理機能を使う場合です。OpenAPI文書が既にあるなら、npxでPrismを起動するだけで数分のうちにモックサーバーが立ち上がります。

OpenAPIが無い既存APIでもモックは作れますか？

作れます。1つは実際の通信を記録して再生する方式で、WireMockには実APIへのプロキシ経由で応答を記録し、スタブ定義として保存する機能があります。もう1つは代表的な応答を手で書き起こす方式。ただし手書きは契約ドリフトの主要因になるため、記録方式を選ぶか、この機会にOpenAPIを起こしてしまうほうが後の維持は楽です。既存APIの棚卸しはAPI管理とは？APIマネジメントの仕組み・構成要素とゲートウェイとの違いを実装者向けに解説【2026年】で扱う管理基盤の整備と合わせて進めると無駄がありません。

モックで検証したのに本番で動かないのはなぜですか？

ほぼすべてが契約ドリフト、つまりモック定義と本番APIの実装がずれていることに起因します。典型は、nullを返す可能性のあるフィールドがモックでは常に値を持っていた、日付の書式がISO 8601とUnix時刻で食い違っていた、エラー時のレスポンス構造が正常時と別物だった、という3パターンです。モックをOpenAPIから生成し、本番APIの応答も同じ定義で検証する二重化を入れると、この種の不整合は結合前に検出できます。

APIモッキングとサービス仮想化はどう使い分けますか？

APIモッキングは特定のエンドポイント群を軽量に代替する手法で、開発チーム内で完結します。サービス仮想化は、メインフレームやメッセージキューを含む複数の依存システムを性能特性まで模擬する商用寄りの領域。代替したい相手がHTTP APIに限られるならモッキング、複数プロトコルにまたがり負荷試験でも使うならサービス仮想化の製品を検討します。中小規模のWeb開発では前者で足りるケースが大半です。

関連記事

• モックとは？スタブとの違い・テストダブル5分類と単体テストでの使い分けを実装者向けに解説：プロセス内のテストダブルの分類と使い分けを扱っており、本記事のネットワーク層モックと対になります。
• 契約テストとは？Pactによる消費者駆動契約の実装とCI組み込みを実装者向けに解説：契約ドリフトを継続的に検知する仕組みを、実装とCI設定の両面から解説しています。
• API管理とは？APIマネジメントの仕組み・構成要素とゲートウェイとの違いを実装者向けに解説【2026年】：モックの前提となるAPI仕様の管理基盤をどう整えるかをまとめています。
• E2E（エンドツーエンド）テストのベストプラクティス｜結合テストとの違いとツール選定：モックから本物のAPIへ切り替えるべきテスト層の設計判断に直結します。