構築するために偽のAPIが必要です。バックエンドがまだ準備できていない、サードパーティサービスがレート制限されている、または単にライブサーバーにアクセスせずにテストを実行したい場合があります。通常の答えはモックです。問題は、それをどのようにセットアップするかです。
GUIをクリックしてルートと固定応答を定義できます。それは一度だけなら問題ありません。しかし、デスクトップアプリで手作業で構築したモックは、再現が難しく、バージョン管理が困難で、CIやAIコーディングエージェントが単独で再現することは不可能です。コマンドラインから定義するモックは異なります。それはスクリプト内のコマンドであり、パイプライン内のステップであり、エージェントが実行できる行です。あなたが入力するものは、マシンも入力できます。
このガイドでは、2つの方法を説明します。1つ目は、一般的なオープンソースの方法です。これは、ファイルから直接実行する単一バイナリのモックサーバーで、スペックまたはJSONファイルが1つのコマンドでライブエンドポイントになります。次に、Apidog CLIの方法です。これは動作が異なり、それ自体を理解する価値があります。まずオプションの全体像を知りたい場合は、最高のAPIモックツールのまとめとREST APIモックツールのガイドの両方が、より広い視点を提供します。
一般的な方法：ファイルからモックサーバーを実行する
従来のCLIモックは、ファイルに指定する小さなバイナリです。スペックまたはデータファイルを与えると、ローカルポートで実際のHTTPエンドポイントを提供します。プロジェクトもログインもアカウントも不要です。これらのツールは1つのことをします。それは、ファイルを呼び出し可能な偽のAPIに変えることです。3つのツールがほぼすべてのケースをカバーします。
Prism: OpenAPIスペックを提供
既にOpenAPIファイルをお持ちの場合、StoplightのPrismは、最も手軽に実行できるモックです。これはpaths、例、スキーマを読み取り、契約に一致する応答を提供します。
npx @stoplight/prism-cli mock ./openapi.yaml
これにより、http://127.0.0.1:4010でサーバーが起動し、スペック内のすべての操作が設定されます。Prismは、応答に対して定義したexampleを返すか、省略した場合はスキーマから有効なランダムなものを生成します。また、受信リクエストをスペックに対して検証するため、不正な形式の呼び出しは、サイレントに通過するのではなく、適切な422を受け取ります。動作していることを確認するには、次のように呼び出します。
curl http://127.0.0.1:4010/orders/123
Prismはステートレスなので、POSTは何も永続化しません。これは、モックが契約に忠実であることを望む場合のポイントです。グローバルインストールの場合、npm install -g @stoplight/prism-cliを実行し、npxを削除します。
Mockoon CLI: データファイルをヘッドレスで実行
Mockoon CLIは、無料のMockoonデスクトップアプリからエクスポートしたデータファイル、またはプレーンなOpenAPIスペックからモックを実行します。デスクトップアプリでは視覚的にルートを構築できますが、CLIは同じ環境をCIまたはサーバー上でヘッドレスで実行します。
npx @mockoon/cli start --data ./env.json
--dataをMockoon環境ファイルまたはOpenAPI JSON/YAMLファイルに向けると、すぐにサービスが提供され、デフォルトでポート3000を使用します。--portを追加して変更できます。データファイルが以前のMockoonバージョンからのものである場合、CLIは元のファイルに触れずにメモリ内で移行します。永続的なmockoon-cliコマンドのために、npm install -g @mockoon/cliでグローバルにインストールします。これは、ベアなスペックよりもリッチで手動調整されたルートを必要とし、GUIなしで実行したい場合に最適です。RESTful API用の軽量モックサーバーは、しばしばこのカテゴリに分類されます。
json-server: JSONからREST APIを偽装
まだスペックがない場合、json-serverが最も迅速な方法です。データ記述のプレーンなJSONファイルを記述すると、その周りに完全なREST APIが構築されます。
npx json-server db.json
posts配列を含むdb.jsonが与えられると、http://localhost:3000/postsで実際のGET、POST、PUT、PATCH、DELETEが提供されます。POSTは実際にレコードを追加し、ファイルに書き戻すため、Prismでは得られないステートフルな動作が無料で手に入ります。クエリパラメータを介したフィルタリング、ソート、ページネーションも利用できます。常にPATHに含めたい場合は、npm install -g json-serverでグローバルにインストールしてください。
これがオープンな方法です。各ツールは単一のバイナリで、1つのファイルから実行され、他には何も必要ありません。トレードオフとして、それぞれが独立しています。モックは実際の設計、テスト、ドキュメントとは別に存在し、ファイルと実行中のプロセスを自分で同期させる必要があります。正確なリクエストマッチングやリプレイが必要な場合は、MockServerやWireMockがより深く対応しますが、Javaランタイムのコストがかかります。
Apidog CLIの方法：スペックをインポートし、期待値をスクリプト化する
Apidogのモックは異なります。これを正しく理解することで混乱を避けることができます。apidog CLIは、ファイルからローカルモックサーバーを起動しません。apidog mock ./openapi.yamlというコマンドはありません。代わりに、Apidogがモックをホストし、CLIはスペックを与え、カスタム応答をスクリプト化する方法です。
まず正直なところ、Apidogはオープンソースではありません。無料プランのある商用製品です。この無料プランとCLIによって得られるのは、統合されたプロジェクトです。つまり、モック、設計、テストが、3つの別々のファイルと3つの別々のプロセスではなく、1つの信頼できる情報源を共有します。もし、1つのファイルから一時的なモックが必要なだけであれば、より軽量なツールが優れています。もし、モックが実際のAPIの変更に合わせて同期し続けるべきであれば、読み進めてください。
最初にインストールと認証を行います（Apidog CLIインストールガイドにトークンの設定方法が記載されています）。
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
スペックをインポートしてホストされたスマートモックを取得する
最初のステップは、APIをプロジェクトにインポートすることです。OpenAPIファイルをインポートすると、Apidogはすべてのエンドポイントに対してモックURLを自動的に生成します。
apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
ここがApidogがPrismやjson-serverと異なる点です。サーバーを実行するのではなく、インポートによって各操作に対してホストされたスマートモックが提供されます。スマートモックはスキーマのフィールドタイプと名前を読み取るため、emailフィールドはそれらしいメールアドレスを返し、createdAtはランダムな文字列ではなく実際に見えるタイムスタンプを返します。apidog importはSwagger 2.0、Postman、Apidog形式も受け入れるため、既存の定義が1つのコマンドでライブモックになります。
apidog mockでカスタム応答をスクリプト化する
自動生成されたモックは一般的なケースをカバーします。特定のリクエストに対して特定の応答が必要な場合、たとえばあるユーザーIDに対して200、別のユーザーIDに対して404が必要な場合、モックの期待値を追加します。これはapidog mockコマンドグループが管理するものであり、起動するサーバーではなく、それらの期待値に対するCRUD操作です。
apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
リスト表示は構造化されたJSONを返すため、jqを介してパイプし、期待値のIDを見つけて次のコマンドに渡すことができます。期待値を読み取ったり、変更したり、削除したりするには：
apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
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
スキーマを取得し、それに合わせてmock.jsonを記述し、検証してから作成します。検証がゼロ以外の終了コードを返した場合、不正なファイルがプロジェクトに到達する前にパイプラインが停止します。更新についても、mock-updateスキーマキーを使用して同じ3つのステップを実行します。すべてのコマンドは、次に何を_実行すべきか_をあなた、またはエージェントに伝えるagentHints.nextStepsブロックを含むJSONを返します。これにより、このフローは人間だけでなくAIコーディングツールでも利用可能になります。Apidog CLI完全ガイドでは、残りのコマンドグループについて説明しています。
CIへの組み込み
両方の方法がパイプラインに適しています。なぜなら、すべてのコマンドが終了コードとテキスト出力を備えているからです。同じジョブでサーバーベースのモックと統合テストを行う場合、次のようになるかもしれません。
# Prismをバックグラウンドで起動し、それに対してテストを実行
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!
npm test
kill $PRISM_PID
Apidogのフローは形が異なります。モックはホストされているため、開始したり停止したりするローカルプロセスはありません。設定ステップとして期待値を検証して適用し、テストはホストされたモックURLに直接アクセスします。
# 期待値が正しい形式であることを確認し、適用する
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
いずれにしても、誰もボタンをクリックしません。それがCLIからモックを行うすべての理由です。スペックを重視するチーム、CIジョブ、AIエージェントのすべてが、同じコマンドから同じ偽のAPIを立ち上げることができます。
よくある落とし穴
apidog mockでサーバーが起動すると期待すること。 起動しません。apidog mock start、apidog mock serve、またはapidog mock ./file.yamlというコマンドはありません。ホストされたモックを取得するにはスペックをapidog importし、apidog mockはそれらの上にカスタムの期待値を管理します。ファイルから起動するローカルプロセスが必要な場合は、Prism、Mockoon CLI、またはjson-serverを使用します。
書き込み時にスキーマの手順をスキップすること。 apidog mock createとupdateは--fileを受け取りますが、形式が間違っていると失敗したり、意図しないものを書き込んだりします。常に最初にcli-schema getとcli-schema validateを実行してください。これは2つの追加コマンドですが、デバッグセッションを節約できます。
スペックが薄いためPrismが空に見えること。 Prismのモックは、あなたの例と同じくらいしか機能しません。応答にexampleがなく、スキーマが曖昧な場合、曖昧なデータしか得られません。スペックに例を追加すると、モックがよりシャープになります。
ステートレスなツールからのステートフルな期待値。 PrismとApidogの契約モックは書き込みを永続化しません。POSTの後にGETで新しいレコードを返す必要がある場合は、json-serverまたは希望する形式を返すApidogの期待値を使用してください。
まとめ
CLIからのモックは、クリックの多い作業を、スクリプト化、レビュー、そしてCIやエージェントに渡せるコマンドに変えます。オープンな方法では、ファイルから実行できる単一バイナリサーバーを提供します。OpenAPIスペックにはPrism、ヘッドレスデータファイルにはMockoon CLI、JSONからの即席REST APIにはjson-serverです。Apidogの方法は逆で、スペックを一度インポートしてホストされたスマートモックを取得し、その後apidog mockとcli-schemaの検証ガードでカスタム応答をスクリプト化します。
既にあるものと、モックが必要な場所に基づいて選択してください。1つのファイルから使い捨てのサーバーが必要な場合は、オープンツールが最適です。モックが設計やテストと1つのプロジェクト内で同期し続けることを望むなら、Apidogをダウンロードし、CLIをインストールして、マウスに触れることなくモックを立ち上げてください。