DEV Community

Cover image for CLIでAPIをモックする方法
Akira
Akira

Posted on • Originally published at apidog.com

CLIでAPIをモックする方法

構築中のフロントエンドや統合テストには、偽のAPIが必要になることがあります。バックエンドが未完成、サードパーティAPIにレート制限がある、本番サーバーへ接続せずに検証したい、といった場面です。一般的な解決策はモックですが、重要なのは「再現可能な方法でどうセットアップするか」です。

今すぐApidogを試す

GUIでルートや固定レスポンスを設定する方法は、単発の検証には便利です。ただし、デスクトップアプリで手作業により作成したモックは、再現・バージョン管理・CI実行が難しくなります。CLIで定義すれば、モックはスクリプトの一部になります。CIパイプラインやAIコーディングエージェントも、同じコマンドを実行して同じ環境を再現できます。

この記事では、次の2つのアプローチを紹介します。

  1. OpenAPIやJSONファイルからローカルモックサーバーを起動するオープンソースツール
  2. Apidog CLIでスペックをインポートし、ホスト型モックの期待値を管理する方法

ツール選定を先に比較したい場合は、最高のAPIモックツールとREST APIモックツールも参照してください。

一般的な方法：ファイルからモックサーバーを実行する

従来のCLIモックツールは、スペックまたはデータファイルを読み込み、ローカルポートでHTTPエンドポイントを公開します。通常、プロジェクト作成・ログイン・アカウント登録は不要です。

用途別に選ぶなら、次の3つでほぼカバーできます。

ツール 入力 向いている用途
Prism OpenAPI 契約に沿ったステートレスなモック
Mockoon CLI Mockoon環境ファイル / OpenAPI GUIで作ったモックをCIで実行
json-server JSONデータ CRUDを伴う簡易REST API

Prism：OpenAPIスペックをそのまま提供する

OpenAPIファイルがすでにあるなら、StoplightのPrismを使うと最短でモックを起動できます。paths、レスポンス例、スキーマを読み込み、契約に一致するレスポンスを返します。

npx @stoplight/prism-cli mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

デフォルトでは http://127.0.0.1:4010 で起動します。スペックに定義された操作へリクエストできるようになります。

curl http://127.0.0.1:4010/orders/123
Enter fullscreen mode Exit fullscreen mode

Prismの主な挙動は次のとおりです。

  • レスポンスに example があれば、その値を返す
  • example がない場合は、スキーマに基づく有効なランダムデータを生成する
  • リクエストをOpenAPIスペックに対して検証する
  • 不正なリクエストはサイレントに通さず、422 を返す

グローバルにインストールする場合は、次を実行します。

npm install -g @stoplight/prism-cli
prism mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Prismはステートレスです。たとえば POST を送っても、データは永続化されません。契約どおりの入出力を確認したい場合に適しています。

Mockoon CLI：データファイルをヘッドレスで実行する

Mockoon CLIは、Mockoonデスクトップアプリからエクスポートした環境ファイル、またはOpenAPI JSON/YAMLファイルを使ってモックを起動できます。

npx @mockoon/cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

--data にはMockoon環境ファイルまたはOpenAPIファイルを指定します。デフォルトではポート 3000 を使用します。

npx @mockoon/cli start --data ./env.json --port 4010
Enter fullscreen mode Exit fullscreen mode

この構成は、次のようなワークフローに向いています。

  1. ローカルではMockoonデスクトップアプリでルートやレスポンスを調整する
  2. 環境ファイルをリポジトリへコミットする
  3. CIではMockoon CLIを使って同じファイルをヘッドレス実行する

環境ファイルが古いMockoonバージョンの形式でも、CLIは元ファイルを書き換えず、メモリ上で移行します。

グローバルに利用する場合は次のとおりです。

npm install -g @mockoon/cli
mockoon-cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

OpenAPIだけでは表現しにくい、手動調整済みのルートやレスポンスをCIで再現したい場合に有効です。RESTful API用の軽量モックサーバーも、この用途に該当します。

json-server：JSONからREST APIを作る

まだOpenAPIスペックがなく、データだけで簡易APIを作りたい場合は、json-serverが手軽です。

まず、db.json を作成します。

{
  "posts": [
    {
      "id": 1,
      "title": "最初の投稿",
      "published": true
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

次にサーバーを起動します。

npx json-server db.json
Enter fullscreen mode Exit fullscreen mode

これで http://localhost:3000/posts に対して、以下のREST操作を利用できます。

curl http://localhost:3000/posts

curl -X POST http://localhost:3000/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"新しい投稿","published":false}'
Enter fullscreen mode Exit fullscreen mode

json-server は GET、POST、PUT、PATCH、DELETE を提供します。POST の内容は実際にデータへ追加され、ファイルへ書き戻されるため、Prismとは異なりステートフルな検証が可能です。

フィルタリング、ソート、ページネーションもクエリパラメータで利用できます。

グローバルにインストールする場合：

npm install -g json-server
json-server db.json
Enter fullscreen mode Exit fullscreen mode

オープンソースツールを選ぶ際のポイント

これらのツールはいずれも、ファイルから実行できる単一プロセスのモックサーバーです。ローカル開発やCIで短時間にモックを立ち上げる用途に適しています。

一方で、モック定義はAPI設計・テスト・ドキュメントとは別管理になります。スペック、モック設定、実行プロセスをチーム側で同期する必要があります。

より厳密なリクエストマッチングやリプレイが必要な場合は、MockServerやWireMockも選択肢です。ただし、Javaランタイムが必要になります。

Apidog CLIの方法：スペックをインポートし、期待値をスクリプト化する

Apidogのモックは、Prismやjson-serverとは仕組みが異なります。

apidog CLIは、ローカルファイルからモックサーバーを起動するツールではありません。つまり、次のようなコマンドはありません。

apidog mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Apidogではモックがホストされ、CLIは以下の操作を行います。

  1. APIスペックをプロジェクトへインポートする
  2. ホストされたモックURLを取得する
  3. 特定条件向けのカスタム期待値をCLIで作成・更新・削除する

Apidogはオープンソースではなく、無料プランを持つ商用製品です。モック、API設計、テストを同じプロジェクトで管理できる点が特徴です。

一時的にローカルモックを起動したいだけなら、Prismやjson-serverの方が軽量です。一方、API設計の変更に合わせてモックとテストを同期させたい場合は、Apidogのワークフローが適しています。

まずCLIをインストールして認証します。アクセストークンの設定はApidog CLIインストールガイドを参照してください。

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

スペックをインポートしてホスト型スマートモックを取得する

OpenAPIスペックをApidogプロジェクトへインポートします。

apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

インポート後、Apidogは各エンドポイントに対してホスト型モックURLを生成します。

この方法では、ローカルサーバーを起動・停止する必要はありません。スキーマのフィールド型や名前を読み取り、モックレスポンスを生成します。たとえば、email フィールドにはメールアドレスらしい値、createdAt にはタイムスタンプらしい値が生成されます。

apidog import はOpenAPIに加え、Swagger 2.0、Postman、Apidog形式も受け入れます。

apidog mock でカスタム応答をスクリプト化する

自動生成モックで不足する場合は、特定のリクエストに対する期待値を追加します。

たとえば、ユーザーIDに応じて異なるレスポンスを返すケースです。

  • /users/1 は 200
  • /users/999 は 404

apidog mock はモックサーバーを起動するコマンドではなく、こうした期待値をCRUD操作するコマンドグループです。

まず、利用可能なサブコマンドと既存の期待値を確認します。

apidog mock --help

apidog mock list --project <PROJECT_ID>

apidog mock list \
  --project <PROJECT_ID> \
  --http-api-id <ENDPOINT_ID>
Enter fullscreen mode Exit fullscreen mode

出力は構造化JSONなので、jq を使って期待値IDを取得し、次の処理へ渡せます。

apidog mock list --project <PROJECT_ID> | jq .
Enter fullscreen mode Exit fullscreen mode

期待値の取得・更新・削除には次のコマンドを使います。

apidog mock get --project <PROJECT_ID>

apidog mock update \
  --project <PROJECT_ID> \
  --file ./mock.json

apidog mock delete --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

create と update では、期待値を定義した --file を指定します。

書き込む前に期待値ファイルを検証する

期待値JSONを推測で作成せず、CLIスキーマを取得して検証してください。

apidog cli-schema get mock-create

apidog cli-schema validate mock-create --file ./mock.json

apidog mock create \
  --project <PROJECT_ID> \
  --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

実装手順は次の3ステップです。

  1. cli-schema get で必要な形式を確認する
  2. スキーマに合わせて mock.json を作成する
  3. cli-schema validate 成功後に mock create を実行する

検証が失敗するとゼロ以外の終了コードが返るため、不正な設定をプロジェクトへ書き込む前にCIを停止できます。

更新時も同じ流れです。

apidog cli-schema get mock-update

apidog cli-schema validate mock-update --file ./mock.json

apidog mock update \
  --project <PROJECT_ID> \
  --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

コマンド出力には、次の実行候補を示す agentHints.nextSteps ブロックが含まれます。そのため、このワークフローは人間の開発者だけでなく、AIコーディングエージェントにも適しています。より多くのCLIコマンドについては、Apidog CLI完全ガイドを参照してください。

CIへ組み込む

CLIベースのモックは、終了コードと標準出力を使えるためCIと相性が良い構成です。

PrismをCIで起動してテストする

Prismをバックグラウンドで起動し、テスト完了後に停止します。

# Prismをバックグラウンドで起動し、それに対してテストを実行
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

npm test

kill $PRISM_PID
Enter fullscreen mode Exit fullscreen mode

テスト失敗時にもプロセスを確実に停止するなら、trap を使います。

npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

trap 'kill $PRISM_PID' EXIT

npm test
Enter fullscreen mode Exit fullscreen mode

Apidogの期待値をCIで適用する

Apidogのモックはホスト型なので、ローカルプロセスの起動・停止は不要です。CIでは期待値の検証と適用を設定ステップとして実行し、テストからホスト型モックURLへアクセスします。

# 期待値ファイルを検証してから適用する
apidog cli-schema validate mock-create --file ./mock.json

apidog mock create \
  --project <PROJECT_ID> \
  --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

どちらの方法でも、手動でボタンをクリックする必要はありません。スペック、モック設定、テストをコマンドとして扱えるため、開発環境・CI・AIエージェントで同じ手順を実行できます。

よくある落とし穴

apidog mock でローカルサーバーが起動すると考える

起動しません。以下のようなコマンドはありません。

apidog mock start
apidog mock serve
apidog mock ./file.yaml
Enter fullscreen mode Exit fullscreen mode

Apidogでホスト型モックを使う場合は、まず apidog import でスペックをインポートします。その後、apidog mock でカスタム期待値を管理します。

ローカルファイルからモックプロセスを起動したい場合は、Prism、Mockoon CLI、json-serverを使用してください。

書き込み前のスキーマ検証を省略する

apidog mock create と apidog mock update は --file を受け取りますが、JSON形式が正しくないと失敗するか、意図しない設定になる可能性があります。

必ず次の順序で実行してください。

apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

追加の2コマンドで、後から行うデバッグを減らせます。

OpenAPIスペックが薄く、Prismのレスポンスが期待どおりにならない

Prismのモック品質は、OpenAPIスペックに依存します。

レスポンスに example がなく、スキーマの情報も曖昧なら、生成されるモックデータも曖昧になります。期待するレスポンス例をスペックへ追加してください。

responses:
  "200":
    description: 注文の取得に成功
    content:
      application/json:
        schema:
          type: object
          properties:
            id:
              type: string
            status:
              type: string
        example:
          id: "123"
          status: "paid"
Enter fullscreen mode Exit fullscreen mode

ステートレスなモックに永続化を期待する

PrismとApidogの契約モックは、書き込みを永続化しません。

POST の後に GET で新しいレコードを取得するようなステートフルな検証が必要なら、json-serverを使用してください。あるいは、必要なレスポンスを返すApidogの期待値を設定します。

まとめ

CLIでモックを扱うと、手作業のクリック操作を、レビュー・再実行・CI実行できるスクリプトへ置き換えられます。

  • OpenAPIスペックから契約準拠のモックを起動するならPrism
  • Mockoonで作成した環境をCIで実行するならMockoon CLI
  • JSONデータからステートフルなREST APIを作るならjson-server
  • API設計、モック、テストを1つのプロジェクトで管理するならApidog

使い捨てのローカルモックが必要なら、ファイルから起動できるオープンソースツールが適しています。モックを設計・テストと同期し続けたいなら、Apidogをダウンロードし、CLIを使ってモック設定を自動化してください。

Top comments (0)