DEV Community

Cover image for ヘッドレスAPIモックツール：GUI不要なCI対応モックサーバー
Akira
Akira

Posted on • Originally published at apidog.com

ヘッドレスAPIモックツール：GUI不要なCI対応モックサーバー

ヘッドレスAPIモックツールは、OpenAPI仕様や設定ファイルからAPIのモックサーバーを起動し、GUIなしでCLI、CI、Docker、フロントエンド開発スクリプトから実行するための仕組みです。この記事では、APIモックにおける「ヘッドレス」の意味、Prism、WireMock、Mockoon CLIの使い方、そしてApidogを使ってスキーマ駆動のモックを運用する方法を実装寄りに整理します。まず概念を確認したい場合は、モックAPIとは何かから始めてください。

今すぐApidogを試す

APIモックにおける「ヘッドレス」とは

モックサーバーは、実バックエンドの代わりにHTTPリクエストへレスポンスを返すプロセスです。フロントエンド、E2Eテスト、APIクライアントの実装を、バックエンド完成前に進められます。

「ヘッドレス」とは、GUIを使わずにモックを起動・停止・利用できることです。典型的には次のように実行します。

mock-tool start --spec ./openapi.yaml --port 4010
Enter fullscreen mode Exit fullscreen mode

ヘッドレスモックが必要になる場面は明確です。

  • CIでフロントエンドテストやAPIテストを安定して実行したい
  • docker-compose内でバックエンドの代替サービスとして起動したい
  • チームメンバーが同じモックをローカルで再現したい
  • プルリクエストごとのプレビュー環境で一時的にAPIを用意したい

GUIモックツールはレスポンス設計には便利ですが、CIやDockerで使うにはCLI、Dockerイメージ、またはホスト型URLが必要です。

仕様駆動型と設定駆動型モック

ヘッドレスモックは大きく2種類に分けられます。

仕様駆動型

仕様駆動型ツールは、OpenAPIなどの仕様ファイルを読み込み、そこからレスポンスを生成します。

paths:
  /users/{id}:
    get:
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  email:
                    type: string
Enter fullscreen mode Exit fullscreen mode

この方式では、API仕様がモックの真実の源になります。フィールドを仕様に追加すると、モックもその変更を反映します。契約とモックがずれにくいのが利点です。

設定駆動型

設定駆動型ツールは、JSONファイル、スタブルール、記録済みレスポンスなどを使ってモックを定義します。

{
  "request": {
    "method": "GET",
    "url": "/users/1"
  },
  "response": {
    "status": 200,
    "jsonBody": {
      "id": 1,
      "email": "alice@example.com"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

この方式は、複雑な条件分岐、エラーケース、ステートフルなシナリオを作りやすい一方で、API仕様との同期を手動で維持する必要があります。

多くのチームでは、通常のレスポンスは仕様駆動型で生成し、特殊ケースだけ設定駆動型で上書きする運用が現実的です。より詳しい流れはAPIモックのガイドでも確認できます。

ヘッドレスモックの選択肢

ここでは、GUIなしで実行できる代表的なツールを比較します。

Prism (Stoplight)

Prismは、OpenAPI 2/3またはPostman Collectionを読み込み、CLIからモックサーバーを起動できます。

prism mock openapi.yaml
Enter fullscreen mode Exit fullscreen mode

デフォルトでは、Prismは次のURLでリッスンします。

http://127.0.0.1:4010
Enter fullscreen mode Exit fullscreen mode

仕様内の examples がある場合は、それをレスポンスとして返します。

responses:
  "200":
    description: OK
    content:
      application/json:
        examples:
          success:
            value:
              id: 1
              email: alice@example.com
Enter fullscreen mode Exit fullscreen mode

動的なサンプルデータを生成したい場合は、-d を付けます。

prism mock openapi.yaml -d
Enter fullscreen mode Exit fullscreen mode

Prismはスキーマから有効な値を生成し、x-faker 拡張によるFaker連携もサポートします。

properties:
  email:
    type: string
    x-faker: internet.email
Enter fullscreen mode Exit fullscreen mode

Prismが向いているケースは次のとおりです。

  • OpenAPIファイルを中心にAPI契約を管理している
  • CIで軽量なモックをすぐ起動したい
  • 仕様ファーストでモックを運用したい

WireMock

WireMockはJavaベースの成熟したHTTPモックサーバーです。スタンドアロンjarとして起動できます。

java -jar wiremock-standalone-3.x.x.jar --port 9099
Enter fullscreen mode Exit fullscreen mode

WireMockでは、リクエスト条件とレスポンスをスタブとして定義します。

{
  "request": {
    "method": "GET",
    "url": "/users/1"
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "jsonBody": {
      "id": 1,
      "name": "Alice"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

このファイルを mappings ディレクトリに配置してWireMockを起動すると、対象エンドポイントにモックレスポンスを返せます。

java -jar wiremock-standalone-3.x.x.jar \
  --port 9099 \
  --root-dir ./wiremock
Enter fullscreen mode Exit fullscreen mode

WireMockは次のような用途に向いています。

  • URL、ヘッダー、クエリ、ボディを細かくマッチングしたい
  • ステートフルなシナリオをテストしたい
  • 実サービスの通信を記録して再生したい
  • JVM中心の開発環境で使いたい

OpenAPIから自動生成するというより、複雑なHTTP挙動を再現するモックに強いツールです。

Mockoon CLI

Mockoonはデスクトップアプリでモック環境を作成し、それをCLIでヘッドレス実行できます。

mockoon-cli start --data ./environment.json --port 3000
Enter fullscreen mode Exit fullscreen mode

Mockoonの基本フローは次のとおりです。

  1. デスクトップアプリでルート、レスポンス、ルールを作成する
  2. 環境を environment.json として保存する
  3. CIやサーバーでは mockoon-cli で起動する

Dockerで実行する場合は、公式イメージまたは dockerize コマンドを使えます。

mockoon-cli dockerize \
  --data ./environment.json \
  --port 3000 \
  --output ./Dockerfile
Enter fullscreen mode Exit fullscreen mode

Mockoonが向いているケースは次のとおりです。

  • GUIでモックを設計したい
  • その設定をCIやDockerで再利用したい
  • レスポンステンプレートやプロキシモードを使いたい

Apidogモックサーバー

Apidogは、API設計、ドキュメント、テスト、モックを同じプロジェクトで扱うAPIプラットフォームです。モックサーバーはスキーマ駆動型で、APIを定義またはインポートすると、追加設定なしでモックを生成できます。

ApidogのSmart Mockは、フィールド名と型を読み取り、より現実的な値を返します。たとえば次のようなフィールドを認識します。

  • email
  • avatar
  • username
  • phone
  • date
  • IP

単なる "string" ではなく、フィールドの意味に近い値を返せるため、フロントエンドの表示確認やテストデータとして使いやすくなります。

より細かく制御したい場合は、Faker.js式を利用できます。

{{$person.fullName}}
{{$number.int(min=1,max=100)}}
Enter fullscreen mode Exit fullscreen mode

リクエスト条件に応じたカスタムモックルールも利用できます。

ヘッドレス利用では、ApidogのCloud Mock URLを使えます。

https://mock.apidog.com/...
Enter fullscreen mode Exit fullscreen mode

CIジョブやチームメンバーは、ローカルでモックサーバーを起動せずにこのURLを呼び出せます。ローカルモックも 127.0.0.1 で実行でき、イントラネットIPにバインドすれば他のマシンからアクセスできます。

モックがAPIデザイン、ドキュメント、テストと同じプロジェクトから生成されるため、個別のモック設定ファイルがAPI契約からずれるリスクを減らせます。

比較

ツール 真実の源 ヘッドレス実行 リアルなデータ 最適な用途
Prism OpenAPI / Postmanファイル prism mock spec.yaml ダイナミックモード (-d) + x-faker 純粋な仕様ファーストのCLIモック
WireMock スタブルール / 記録 スタンドアロンjar レスポンステンプレーティング 複雑なマッチング、JVMスタック、記録/再生
Mockoon CLI GUIで構築された環境 mockoon-cli start + Docker テンプレーティングヘルパー ビジュアル設計、ヘッドレスデプロイ
Apidog プロジェクト内のAPIスキーマ Cloud Mock URL + ローカルサーバー Smart Mock + Faker.js デザイン、ドキュメント、テストと連携したスキーマ駆動型モック

選び方の目安は次のとおりです。

  • OpenAPIファイルだけで軽量に起動したい: Prism
  • 複雑なHTTPマッチングや記録/再生が必要: WireMock
  • GUIで作ったモックをCIに持ち込みたい: Mockoon CLI
  • API設計、ドキュメント、テスト、モックを同じ契約で管理したい: Apidog

より広い選択肢を確認したい場合は、最高のAPIモックツールのまとめも参考になります。

CIでヘッドレスモックを実行する

CIでの基本パターンはシンプルです。

  1. モックサーバーをバックグラウンドで起動する
  2. テスト対象のAPIベースURLをモックに向ける
  3. テストを実行する
  4. モックサーバーを停止する

Prismを使う場合は、次のように書けます。

# モックをバックグラウンドで起動
prism mock ./openapi.yaml &
MOCK_PID=$!

# フロントエンドまたはAPIテストをモックに向けて実行
API_BASE_URL=http://127.0.0.1:4010 npm test

# 後片付け
kill $MOCK_PID
Enter fullscreen mode Exit fullscreen mode

GitHub Actionsでは、たとえば次のように組み込めます。

name: test-with-mock

on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - run: npx @stoplight/prism-cli mock ./openapi.yaml &

      - run: API_BASE_URL=http://127.0.0.1:4010 npm test
Enter fullscreen mode Exit fullscreen mode

Apidogを使う場合は、Cloud Mock URLにテストを向ければ、CI内でモックプロセスを起動しなくても済みます。

API_BASE_URL=https://mock.apidog.com/your-project npm test
Enter fullscreen mode Exit fullscreen mode

ローカルモックを使う場合も、他のCLIツールと同じように起動してからテストを実行します。モックは現在のスキーマから応答するため、API契約の変更を反映しやすくなります。

モックに対してCLIテストを実行する

ヘッドレスモックを用意したら、次はそのモックに対してテストを自動実行します。

ApidogのCLIである apidog-cli もヘッドレスで動作します。apidog run を使うと、CIからテストシナリオを実行できます。

apidog run
Enter fullscreen mode Exit fullscreen mode

主な用途は次のとおりです。

  • APIテストシナリオをCIで実行する
  • CSVまたはJSONを使ってデータ駆動テストを行う
  • CLI、HTML、JSON形式のレポートを生成する

詳細な流れは、コマンドラインからREST APIをテストするで確認できます。CLIオプションを整理したい場合は、完全なCLIガイドが参考になります。NewmanやPostman CLIとの違いを理解したい場合は、Apidog CLIとPostman CLIの比較も確認してください。

Docker Composeでモックを使う

フロントエンドとモックを同じDocker Composeネットワークで起動する場合は、モックを1つのサービスとして定義します。

Prismの例です。

services:
  mock-api:
    image: stoplight/prism:4
    command: mock -h 0.0.0.0 /tmp/openapi.yaml
    volumes:
      - ./openapi.yaml:/tmp/openapi.yaml
    ports:
      - "4010:4010"

  frontend:
    build: .
    environment:
      API_BASE_URL: http://mock-api:4010
    depends_on:
      - mock-api
Enter fullscreen mode Exit fullscreen mode

この構成では、frontend コンテナからは http://mock-api:4010 でモックにアクセスできます。ローカルホストではなく、Composeのサービス名を使うのがポイントです。

モックとAIコーディングエージェント

Cursor、Claude、VS CodeなどでAIエージェントを使ってコードを書く場合、エージェントがAPI契約を参照できると、生成されるクライアントコードとモックレスポンスの整合性を保ちやすくなります。

Apidog MCPサーバーを使うと、AIエージェントがAPI仕様を直接読み取れます。これにより、モックが返すスキーマと、エージェントが生成する型定義やAPIクライアントが同じ契約を参照できます。

よくある質問

ヘッドレスモックはモックサーバーと同じですか？

ほぼ同じですが、「ヘッドレス」は実行方法を指します。モックサーバーは偽のレスポンスを返すプロセス全般です。ヘッドレスモックは、そのモックサーバーをGUIなしでCLI、Docker、CI、またはホスト型URLから使える形にしたものです。

OpenAPI仕様からヘッドレスモックを生成できますか？

できます。PrismはOpenAPIを直接読み込みます。Apidogはプロジェクト内のAPIスキーマからモックを生成します。仕様駆動型にすると、個別のモック設定を手動更新する必要が減り、契約との整合性を保ちやすくなります。全体のワークフローはAPIモックガイドで確認できます。

ヘッドレスモックはどのようにリアルなデータを返しますか？

ツールごとにデータ生成の仕組みがあります。Prismはダイナミックモードと x-faker でスキーマから値を生成できます。ApidogのSmart Mockは、email や phone のようなフィールド名を認識し、適切な値を返します。さらにFaker.js式で値を細かく制御できます。

サーバーを起動する必要がありますか？

ツールによります。WireMock、Prism、Mockoon CLIは、基本的に自分でモックプロセスを起動します。ApidogはCloud Mock URLを提供しているため、CIやチームメンバーはローカルで何も起動せずにモックを呼び出せます。パイプラインの可動部品を減らしたい場合は、ホスト型URLが便利です。

結論

ヘッドレスAPIモックは、ローカルで手動確認するためのモックを、CI、Docker、チーム開発、プレビュー環境で再利用可能にするための実装パターンです。

PrismはOpenAPIファイルから素早くCLIモックを起動できます。WireMockは複雑なHTTPマッチングや記録/再生に強みがあります。Mockoon CLIはGUIで設計したモックをヘッドレスに実行できます。

Apidogは、APIデザイン、ドキュメント、テスト、モックを同じプロジェクトで管理し、スキーマ駆動型のモックをローカルまたはCloud Mock URLから利用できます。モック設定がAPI契約からずれるのを避けたい場合に有効です。Apidogをダウンロードして、仕様からモックを起動し、CIで活用してください。

Top comments (0)