API Shakedown

API Shakedown

OpenAPI 仕様を渡すだけで、すぐに実行できるテストハーネスが得られます。WireMock のスタブ、コントラクトテスト、堅牢性プローブ、カオスシナリオを、互いの成果物をレビューする LLM エージェントのチームが作成します。

デフォルトでは Ollama 上でローカル実行します。API キーは不要で、データがマシンの外に出ることもありません。クラウドモデル（OpenAI、Anthropic）を使う場合は、ご自身のキーをご用意ください。CLI、Docker イメージ、AI アシスタントから操作できる MCP サーバーとして利用できます。

ステータス：アルファ版（0.1.3）。ローカルの 8B モデルを使い、サンプル仕様で最初から最後まで動作します。

同梱のサンプルを使い、ノート PC 上の qwen3:8b で実際に実行した結果を高速再生しています。生成には約 9 分かかりました。録画：docs/demo.cast。

---

目次

• 理由
• 役立つ場面
• クイックスタート
• 生成されるもの
• 仕組み
• インストール
• 使い方
• 設定
• MCP サーバー
• Docker
• アーキテクチャ
• 制限事項
• ロードマップ
• 開発
• コントリビューション
• ライセンス

理由

API を利用するチームには、手作業で書くのが面倒で、すぐに古くなってしまうものが 3 つ必要です。

1. 開発やテストに使える、実際に即した API モック。
2. 実際の API が仕様と合わなくなったときに知らせるコントラクトテスト。
3. 障害ドリル：API が遅い、不安定、レート制限中、でたらめな応答を返す、あるいは停止した場合、クライアントはどう動作するでしょうか？

API Shakedown は、すでにある仕様からこの 3 つすべてを生成し、その正確さを保ちます。LLM が実行可能なコードを書くことはありません。LLM が提案するのは、応答本文、テストケース、障害シナリオ、テストレコードといったデータです。コードが各項目を仕様に照らして検証し、問題をモデルにフィードバックします。モデルが正しい結果を出せない場合は、決定的な出力にフォールバックします。モデルをまったく使わない場合（--offline）でも、すべての機能が動作します。

活用できる場面

状況	主なチーム	API Shakedown でできること
バックエンドができる前に開発を始める	フロントエンド、モバイル、パートナーとの統合を担当するチーム	合意済みの仕様から仮想サービスを生成するため、バックエンドの提供後や手書きのモックを作成した後ではなく、初日から作業を開始できます。
自分たちで管理していない API に依存している（決済、配送、本人確認、信用情報機関）	フィンテック、eコマース、物流、保険	ベンダーのサンドボックスは、レート制限があったり、不安定だったり、呼び出しごとに課金されたりすることがよくあります。プロバイダーがタイムアウトする場合、レート制限をかける場合、または復旧前に 503 を 2 回返す場合に、アプリがどう動作するかをローカルでテストできます。
クライアントが障害に耐えられることを実証する	マイクロサービスチーム、SRE のゲームデー	クライアントの実行中に、タイムアウト、レート制限、不安定な呼び出し、部分的な停止を切り替え、再試行、バックオフ、フォールバックが実際に機能することを確認できます。
リリース前に仕様とのずれを検出する	API オーナー、プラットフォームチーム、パブリック API チーム	CI で実際のデプロイに対してコントラクトテストを実行し、実装が仕様と一致しなくなった場合に失敗させます。
入力検証を強化する	すべての API チーム	ロバストネスプローブで、不正なリクエストに 500 ではなく 4xx が返ることを確認します。セキュリティレビューを補完するものであり、代替するものではありません。
規制対象またはオフラインの環境	銀行、医療、政府機関	すべてローカルモデル上で動作します。仕様がマシンの外に出ることはないため、多くの AI ツールをまったく使用できない環境でも利用できます。
サービスを移行または書き換える	レガシーシステムのモダナイゼーション	既存の仕様からコントラクトテストを生成し、新しい実装に対して実行することで、同じ動作をすることを確認できます。
AI アシスタントを使って作業する	Claude やその他の MCP クライアントを使用する開発者	アシスタントがハーネスを生成し、依頼に応じて障害訓練を実行します。

負荷テストツールやセキュリティスキャナーではなく、仮想サービスは呼び出し間で状態を保持しません。詳しくは制限事項をご覧ください。

クイックスタート

前提条件：Python 3.11 以降、Docker（WireMock 用）、およびモデルを用意した Ollama（--offline またはクラウドモデルを使用する場合を除き、ollama pull qwen3:8b を実行してください）。

pip install api-shakedown
shakedown doctor                                   # is the model ready?
shakedown run openapi.yaml --out my-harness        # minutes on a local model
cd my-harness
docker compose up -d                               # WireMock with your stubs on :8080
pip install -r requirements.txt
SHAKEDOWN_SELECT_STATUS=1 pytest tests/test_contract.py
python chaos/chaos.py on flaky-start               # now point your client at :8080
python chaos/chaos.py off

同梱のサンプルで試すには、shakedown run examples/petstore.yaml --out petstore を実行します。

サンプル仕様に qwen3:8b を使用して実行した例：

Petstore 1.0.0: 5 operations (ollama / qwen3:8b)
Generating test data...
Test data ready (3 Pet).
Generating stubs, contract tests, and chaos scenarios...
  stubs: done
  contracts: done
  chaos: done
  review contracts: approved
  review stubs: approved
  review chaos: approved

Wrote 14 files to harness in 436s: 15 stubs, 11 contract cases, 11 chaos scenarios, 30 probes.
Next: cd harness && docker compose up -d   (then see README.md)

得られるもの

my-harness/
├── README.md                  # generated: how to run it, every scenario, review notes
├── docker-compose.yml         # WireMock 3 serving the stubs (port: SHAKEDOWN_WIREMOCK_PORT)
├── wiremock/mappings/         # stub mappings
├── tests/
│   ├── test_contract.py       # contract tests (cases in contract_cases.json)
│   └── test_robustness.py     # malformed-request probes (cases in robustness_cases.json)
├── chaos/
│   ├── chaos.py               # switch failure scenarios on/off (standard library only)
│   └── chaos_scenarios.json
├── data/dataset.json          # test records and edge-case values per field
├── requirements.txt           # pytest, httpx, openapi-schema-validator
└── shakedown.json             # manifest: counts, review outcome, generation notes

項目	内容
スタブ	すべての操作について、ドキュメントに記載されたすべてのレスポンスを用意します。既知の ID にはその ID のレコードを返し、不明な ID にはドキュメントに記載された 404 を返します。また、X-Shakedown-Status: <status> を指定すると、その他の任意のレスポンスを要求できます。
コントラクトテスト	正常系、ドキュメントに記載されたエラーステータス、境界値をテストします。それぞれのテストで、ステータスコード、Content-Type、本文がレスポンススキーマに適合するかを検証します。スタブまたは実際のデプロイ環境を対象に実行できます。
堅牢性プローブ	スキーマに基づく無効な本文やパラメーター（必須フィールドの不足、型の誤り、範囲外の値、不正な JSON）をテストします。堅牢なサーバーは 4xx を返し、5xx は返しません。
カオスシナリオ	すべてのクライアントが耐えられるべき 7 つの基本的な障害に加え、LLM が API に対して実行するシナリオを用意します。
テストデータ	エンティティごとの現実的で一貫性のあるレコードをスタブとテストで共有し、すべてのフィールドにエッジケースの値を用意します。

基本的なカオスシナリオ：

シナリオ	発生すること	回復力のあるクライアントに求められる動作
total-outage	すべてのエンドポイントが 503 を返します	すぐに失敗し、バックオフして、API に過剰なリクエストを送らない
slow-responses	すべてのレスポンスに 3 s かかります	応答性を維持する
timeouts	すべてのレスポンスに 30 s かかります	自動的に処理を諦め、リソースを解放する
connection-resets	接続がリセットされます	冪等な呼び出しをバックオフしながら再試行する
flaky-start	最初の 2 回の呼び出しが 503 で失敗し、その後回復します	再試行して 3 回目の試行で成功する
rate-limited	最初の 3 回の呼び出しが 429 を返します	Retry-After に従う
truncated-json	成功レスポンスの本文が JSON の途中で切断されます	解析エラーを報告し、決してクラッシュしない

実際の実行では、LLM を対象としたシナリオに createPet が 503 で 3 回失敗した後に回復する、listPets がレート制限される、getPet で必須フィールドが失われる などがあります。

仕組み

flowchart LR
    spec[/"OpenAPI spec"/] --> load["Load, validate,<br/>normalize, chunk"]
    load --> data["Test data agent"]
    data --> stubs["Stub agent"]
    data --> contracts["Contract agent"]
    data --> chaos["Chaos agent"]
    stubs --> review{"Reviewer agent"}
    contracts --> review
    chaos --> review
    review -- "blocker: revise with feedback" --> stubs
    review -- "blocker" --> contracts
    review -- "blocker" --> chaos
    review -- "approved, or budget spent" --> coord["Coordinator"]
    coord --> harness[/"Harness directory"/]

1. 仕様レイヤー：パスまたは URL から YAML/JSON を読み込み、検証します（問題は警告になります）。安全に $ref をインライン化し、大きな仕様が小規模なモデルにも収まるよう、操作をプロンプトサイズのチャンクに分割します。
2. テストデータエージェントが最初に実行されます。スタブとテストはそのレコードを共有します。
3. スタブ、コントラクト、カオスの各エージェントが並行して実行されます。
4. レビュアーが各成果物を評価します。ブロッカーがある場合、フィードバックとともに作成者に差し戻します。差し戻しの回数には上限があり、提案は注記として残されます。
5. コーディネーターがテストハーネスとその README を組み立てます。修正予算が尽きた時点で、レビュアーが却下した項目も含まれます。

すべてのエージェントは同じパターンに従います。これにより、小規模なローカルモデルでも安定して動作します。

sequenceDiagram
    participant A as Agent
    participant M as LLM
    participant C as Code checks
    A->>M: task + JSON schema (constrained decoding on Ollama)
    M-->>A: proposal (bodies, cases, scenarios, records)
    A->>C: validate against the spec
    alt problems found
        C-->>A: exact errors, e.g. "listPets 200: 'id' is a required property"
        A->>M: fix these problems
        M-->>A: corrected proposal
    end
    A->>A: keep valid items, fall back to deterministic ones for the rest

コードで保証するため、モデルが考慮する必要のないこと：

• スタブでのリクエストの照合、URL パターン、優先順位、パスパラメーターの型。
• スキーマに適合するレスポンス本文。
• ルーティングできるテスト入力（有効なパスパラメーター、必須のクエリパラメーター）、既存の ID を使う成功ケース、存在しない ID を使う 404 ケース。
• 仕様のセキュリティスキームに基づく認証。
• 一貫性のあるカオスシナリオ（「不安定な」障害は回復し、レート制限は 429 になり、部分的な障害では一部のエンドポイントが稼働する）。
• 実際の項目を参照するレビュアーの指摘、および作成者が制御できる項目だけを対象とするブロッカー。

インストール

pip install api-shakedown              # local models via Ollama; includes the MCP server
pip install "api-shakedown[cloud]"     # plus OpenAI and Anthropic

すべてが含まれる Docker イメージを使うこともできます。Docker を参照してください。

生成されたテストハーネスには、Docker（WireMock 用）とテスト実行用の Python が必要です。

使用方法

shakedown doctor                     Check the LLM provider is reachable and ready
shakedown inspect SPEC [--json]      Show the operations the agents will see
shakedown run SPEC [options]         Generate a harness
shakedown version

shakedown run のオプション：

オプション	デフォルト
--out PATH	shakedown-output	ハーネスの出力先（空でないディレクトリの場合は拒否します）
--offline	オフ	LLM を使用せず、数秒で決定的な出力を生成します
--no-review	レビュー有効	レビュアーをスキップします（この例では約 3 倍高速になります）
--max-revisions N	1	レビュー／改訂のラウンド数
--force	オフ	空でないディレクトリに書き込みます（ハーネスのファイルのみ上書きします）
--provider、--model	設定値	この実行で使用する LLM を上書きします

ハーネスの使用方法：

docker compose up -d                                     # stubs on http://localhost:8080
SHAKEDOWN_SELECT_STATUS=1 pytest tests/test_contract.py  # against the stubs
python chaos/chaos.py list | on <scenario> | off         # failure drills
SHAKEDOWN_TARGET_URL=https://api.example.com/v1 pytest tests   # against a real server
SHAKEDOWN_SEED=1 SHAKEDOWN_TARGET_URL=... pytest tests   # create the test records first

SHAKEDOWN_SEED=1 を指定すると、コントラクトテストはまず、仕様に記載された作成操作を使ってサーバー上にテストデータセットのレコードを作成し、終了時に削除します。サーバーに書き込むため、テスト用インスタンスを指定してください。

PowerShell の場合：$env:SHAKEDOWN_SELECT_STATUS = "1"; pytest tests/test_contract.py。

設定

設定は環境変数または .env ファイルから取得されます（.env.example を参照）。すべて任意です。

変数	デフォルト
SHAKEDOWN_PROVIDER	ollama	ollama、openai、または anthropic
SHAKEDOWN_MODEL	プロバイダーごと	qwen3:8b、gpt-5-mini、claude-sonnet-5-5
SHAKEDOWN_OLLAMA_URL	http://localhost:11434	Ollama の実行場所
SHAKEDOWN_BASE_URL		エンドポイントの上書き（例：OpenAI 互換サーバー）
SHAKEDOWN_TIMEOUT	600（Ollama）／120	リクエストごとの秒数
SHAKEDOWN_CONTEXT_WINDOW	16384	Ollama のコンテキストサイズ
SHAKEDOWN_REASONING	モデルのデフォルト	Ollama：推論モデルの思考を有効／無効にします
SHAKEDOWN_AGENT_MODELS		エージェントごとのモデル（例：{"reviewer": "anthropic:claude-sonnet-5-5"}）
SHAKEDOWN_AGENT_REASONING	生成エージェントでは思考オフ	エージェントごとの思考設定（例：{"reviewer": true}）
OPENAI_API_KEY、ANTHROPIC_API_KEY		独自のキーを使用します

モデルを組み合わせる方法も効果的です。ローカルで生成し、より高性能なクラウドモデルでレビューします。

SHAKEDOWN_AGENT_MODELS='{"reviewer": "anthropic:claude-sonnet-5-5"}' shakedown run openapi.yaml

生成されたハーネスは、SHAKEDOWN_TARGET_URL、SHAKEDOWN_SELECT_STATUS、 SHAKEDOWN_SEED、SHAKEDOWN_API_KEY、SHAKEDOWN_BASIC_AUTH、SHAKEDOWN_TIMEOUT、および SHAKEDOWN_WIREMOCK_PORT／SHAKEDOWN_WIREMOCK_URL を読み込みます。

MCP サーバー

shakedown-mcp（stdio）を使うと、Claude Code や Claude Desktop などの MCP クライアントからハーネスを生成し、障害ドリルを実行できます。

ツール
doctor	LLM プロバイダーの準備はできていますか？
inspect_spec	仕様の操作と警告を一覧表示します
generate_harness	進捗通知付きでハーネスを生成します
list_chaos_scenarios	ハーネス内のシナリオを一覧表示します
activate_chaos／deactivate_chaos	実行中の WireMock でシナリオをオン／オフに切り替えます

claude mcp add api-shakedown -- uvx api-shakedown mcp     # Claude Code, nothing to install
claude mcp add api-shakedown -- shakedown-mcp             # Claude Code, after pip install

公式 MCP レジストリでの名前： io.github.anzar-ahsan-commits/api-shakedown。

その他のクライアント（設定内の mcpServers）：

{
  "mcpServers": {
    "api-shakedown": {
      "command": "uvx",
      "args": ["api-shakedown", "mcp"],
      "env": { "SHAKEDOWN_PROVIDER": "ollama" }
    }
  }
}

絶対パスを指定してください。ローカルモデルでの生成には数分かかります。クライアントが長時間のツール呼び出しを中断する場合は、offline または review: false を使用するか、ツールのタイムアウトを延長してください。

Docker

docker build -t api-shakedown .
docker run --rm -v "$PWD:/work" api-shakedown run /work/openapi.yaml --out /work/harness
docker run -i --rm -v "$PWD:/work" --entrypoint shakedown-mcp api-shakedown   # MCP server

イメージはホスト上の Ollama に host.docker.internal で接続します。Linux、PowerShell、クラウドキーについては、DOCKER.md を参照してください。

アーキテクチャ

flowchart TB
    subgraph app["api-shakedown"]
        cli["CLI: shakedown"] --> pipeline["pipeline"]
        mcp["MCP server: shakedown-mcp"] --> pipeline
        pipeline --> agents["agents: testdata, stubs, contracts,<br/>chaos, reviewer, coordinator"]
        agents --> domain["spec, wiremock, contracts,<br/>chaos, testdata (code checks)"]
        pipeline --> harness["harness writer + templates"]
    end
    subgraph core["agentpanel (reusable core)"]
        workflow["Workflow: parallel specialists,<br/>cross-review, bounded revision"]
        structured["structured output:<br/>validate, feed back, retry"]
        llm["providers: Ollama, OpenAI, Anthropic"]
    end
    agents --> workflow
    agents --> structured
    structured --> llm

オーケストレーションコアは、agentpanel として別途公開されています。これは、LangGraph 上で「専門家が草案を作成し、レビュアーが批評し、作成者が修正し、コーディネーターが判断する」ワークフローを実現する、小規模でドメインに依存しないライブラリです。アプリケーションをインポートすることはなく、それをテストで検証しています。

packages/agentpanel/     # the reusable core (its own PyPI package)
src/api_shakedown/       # the application
  spec/                  # loading, validation, $ref resolution, edge cases, samples
  agents/                # the six agents
  templates/             # runners copied into every harness
examples/petstore.yaml   # example spec
tests/                   # offline tests; `-m live` for Ollama + Docker tests

制限事項

• ローカルモデルでの速度：qwen3:8b を使用した場合、5 つの操作の例を最後まで実行するのに約 7 分かかり、その大半はレビューに費やされます。--no-review を指定すると約 2.5 分です。
• 小規模モデルのレビュアーは不完全です：8B のレビュアーが誤ってブロッカーを指摘することがあり、その場合は修正ラウンドが必要になります。可能であれば、レビュアーにはより強力なモデルを使用してください。
• 仕様：OpenAPI 3.0-3.2 に対応しています。Swagger 2.0 は事前に変換する必要があります。他のファイルへの参照はたどらず、自己参照するスキーマも検証しません。
• スタブは静的です：作成呼び出しは新しいレコードを返しますが、スタブは呼び出し間で状態を保持しません。
• スタブに対するプローブ：4xx を記述している操作のみを対象とします。実際のサーバー向けの機能です。
• シード処理には制限があります：SHAKEDOWN_SEED=1 で作成できるのは、仕様で作成が許可され、テストデータの ID を使えるレコードのみです。また、実際のサーバーでは仕様に記載のないルールが適用されることがよくあります。作成できないレコードは警告に一覧表示され、そのレコードを読み取るテストは、手動で作成するまで 404 で失敗します。
• 対象範囲：負荷テストツールでもセキュリティスキャナーでもありません。
• 大規模な仕様はノート PC では時間がかかります：79 個の操作を含む Typesense API は、小規模な仕様なら数分で済むのに対し、ノート PC の GPU で qwen3:8b を使うと、最初から最後まで数時間かかります。より高性能な GPU やクラウドモデルを使うと大幅に高速になります。--offline の場合は数秒です。実環境に近い仕様でのレポートをぜひお寄せください。

ロードマップ

• 大規模な仕様での実行を高速化（バッチごとのプロンプトを小さくし、バッチごとに進捗を表示）
• シード処理の改善：作成レスポンスからサーバーが割り当てた ID を取得し、API キーなどのリソースもシードできるようにする
• ステートフルなスタブ（WireMock のレスポンステンプレート、作成したレコードを後続の呼び出しから参照可能にする）
• 認証失敗のシナリオ（401／403）と、「有効だが厄介な入力で 5xx が発生しない」ことを検証するプローブ
• テストデータセットのレビュー
• 対応するハーネスの追加（k6 の負荷プロファイル、Postman コレクション）

開発

git clone https://github.com/anzar-ahsan-commits/api-shakedown.git
cd api-shakedown
python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e packages/agentpanel -e ".[dev]"
ruff check . && ruff format --check . && mypy
pytest                 # offline: LLMs are faked, about 20 s
pytest -m live         # also uses your local Ollama and Docker

コントリビューション

コントリビューションを歓迎します。CONTRIBUTING.md をご覧ください。セキュリティ上の問題については、SECURITY.md をご覧ください。

ライセンス

MIT © 2026 Anzar Ahsan