Mockoonで動的なレスポンスを返すモックサーバーを構築する

本記事はディップ Advent Calendar 2025の3日目の記事です。
空いていた枠をお借りして投稿しています。

TL;DR

• MockoonのdateTimeShiftヘルパーで「現在時刻から○時間前」のような動的な日時生成が可能
• Docker Composeのprofiles機能で開発環境のみモック有効化

はじめに

API開発やテストにおいて、外部APIのモックサーバーは欠かせない存在です。
今回は、Mockoonを使って動的なレスポンスを返すモックサーバーをDockerで構築する方法を紹介します。

Mockoonとは

GUIとCLIの両方で使えるオープンソースのAPIモックツール
JSONファイルでAPI定義を管理でき、テンプレート機能を使った動的なレスポンス生成が可能

構成

Docker Compose

services:
  mockoon-api:
    image: mockoon/cli:9
    container_name: mockoon_api
    ports:
      - "3000:3000"
    volumes:
      - ./mockoon/api-mock.json:/data/api-mock.json:ro
    command: ["--data", "/data/api-mock.json"]
    environment:
      - TZ=Asia/Tokyo
    profiles:
      - mock

※ profiles: [mock]を指定しているため、docker compose --profile mock upで起動する必要あり

API定義ファイル（api-mock.json）

{
  "uuid": "api-mock",
  "lastMigration": 32,
  "name": "Event Log API Mock",
  "port": 3000,
  "routes": [
    {
      "uuid": "event-log-diff",
      "method": "get",
      "endpoint": "api/v1/events/diff",
      "responses": [
        {
          "uuid": "success-response",
          "body": "（後述）",
          "statusCode": 200,
          "headers": [
            { "key": "Content-Type", "value": "application/json" }
          ],
          "bodyType": "INLINE",
          "disableTemplating": false,
          "default": true
        }
      ],
      "enabled": true
    }
  ],
  "rootChildren": [
    { "type": "route", "uuid": "event-log-diff" }
  ]
}

bodyの内容

bodyには以下のJSONをエスケープした文字列を設定

{
  "total": 1,
  "data": [
    {
      "event_id": "evt_001",
      "event_type": "user.login",
      "event_time": "{{dateTimeShift date=(now) format='yyyy-MM-dd HH:mm:ss' hours=-2}}",
      "user_id": "user_12345",
      "ip_address": "192.168.1.100",
      "status": "success",
      "created_at": "{{dateTimeShift date=(now) format='yyyy-MM-dd HH:mm:ss' hours=-2}}"
    }
  ]
}

JSONのbodyフィールドは文字列のため、改行やダブルクォートのエスケープが必要
JSONエスケープツールなどを使うと簡単に変換可能

動的なレスポンスのポイント

MockoonはHandlebarsベースのテンプレート機能を持っており、dateTimeShiftヘルパーで動的な日時を生成可能

{{dateTimeShift date=(now) format='yyyy-MM-dd HH:mm:ss' hours=-2}}

パラメータ	説明	例
date	基準となる日時	(now) で現在時刻
format	出力フォーマット	yyyy-MM-dd HH:mm:ss
hours, minutes, seconds, days	シフト量	hours=-2 で2時間前

テンプレート機能を有効にするには、"disableTemplating": falseの設定が必要

起動と確認

# モックサーバーを起動
docker compose --profile mock up -d

# イベントログを取得
curl http://localhost:3000/api/v1/events/diff

レスポンス例（2025年12月20日 23:30頃にリクエストした場合）:

{
  "total": 1,
  "data": [
    {
      "event_id": "evt_001",
      "event_type": "user.login",
      "event_time": "2025-12-20 21:30:42",
      "user_id": "user_12345",
      "ip_address": "192.168.1.100",
      "status": "success",
      "created_at": "2025-12-20 21:30:42"
    }
  ]
}

hours=-2を指定しているため、event_timeとcreated_atがリクエスト時刻の2時間前

まとめ

Mockoonを使うことで、動的なレスポンスを返すモックサーバーを簡単に構築できます。
Docker Composeのprofiles機能と組み合わせることで、開発環境でのみモックを有効化する運用も容易です。