PRDからテストまで：Apidog CLIで効率化するエージェント開発ワークフロー

これは、APIテストとAPIライフサイクル管理のためのコマンドラインツールであるApidog CLIをApidogがどのように開発したかを共有する全10回のシリーズです。順番に読むか、興味のある記事に直接アクセスしてください：

実際の例を見てみましょう：あるチームが注文返金に関するPRDとコードベースを持っています。AgentがApidog CLI + SKILLを使用して、OpenAPIを生成し、テストを作成し、検証し、確認するまでの一連の流れをエンドツーエンドで見ていきましょう。

シナリオ

実際のワークフローで全てを具体的に見ていきましょう。

コンテキスト：

あるチームが「注文返金」に関するPRDの作成を終えたばかりです。コードベースには既に対応するルートとコントローラーが存在します。

Agentへのユーザーリクエスト：

「PRDとコードベースに基づいて、返金機能のAPIテストを生成し、検証を実行してください。」

古いアプローチの問題

MCPツールでは、Agentは一連のジレンマに直面します：

Agentは、タスクの実行ではなく、単にパスを決定するために多大な労力を費やします。

CLI + SKILLのパス

CLI + SKILLは、明確なシーケンスで実際のR&Dフローを満たします：

PRDとコードベースからOpenAPIを生成
        ↓
Apidogにインポート
        ↓
単一エンドポイントのテストケースを追加
        ↓
書き込む前に検証
        ↓
ビジネスフローのテストシナリオを生成
        ↓
書き込む前に検証
        ↓
自動テストを実行

各ステップを見ていきましょう。

ステップ1: OpenAPIの生成とインポート

AgentはPRDとコードベースを読み込み、OpenAPI仕様を生成します。

PRD抜粋：

Order Refund API

POST /api/orders/{orderId}/refund
- Request body: { "reason": string, "amount": number }
- Response: { "refundId": string, "status": string, "processedAt": datetime }

GET /api/orders/{orderId}/refund/{refundId}
- Response: { "refundId": string, "status": string, "amount": number }

AgentはOpenAPIを生成します：

{
  "openapi": "3.0.0",
  "paths": {
    "/api/orders/{orderId}/refund": {
      "post": {
        "summary": "Create refund request",
        "parameters": [...],
        "requestBody": {...},
        "responses": {...}
      }
    },
    "/api/orders/{orderId}/refund/{refundId}": {
      "get": {
        "summary": "Get refund status",
        ...
      }
    }
  }
}

Apidogへのインポート：

apidog import --project <projectId> --format openapi --file ./openapi.json

CLI出力：

{
  "success": true,
  "data": {
    "importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],
    "endpointIds": ["ep-001", "ep-002"]
  },
  "agentHints": {
    "summary": "OpenAPIが正常にインポートされました。2つのエンドポイントが作成されました。",
    "nextSteps": [
      "インポートされたエンドポイントをリストして構造を確認する。",
      "各エンドポイントのテストケースを追加する。",
      "完全な返金フローのテストシナリオを作成する。"
    ]
  }
}

ステップ2: 単一エンドポイントのテストケース

Agentはまず「返金エンドポイント」に焦点を当てます。

Agentはエンドポイントを読み込みます：

apidog endpoint get ep-001 --project <projectId>

CLIはエンドポイント構造を返します：

{
  "id": "ep-001",
  "method": "POST",
  "path": "/api/orders/{orderId}/refund",
  "requestBody": {
    "schema": {
      "type": "object",
      "properties": {
        "reason": { "type": "string" },
        "amount": { "type": "number" }
      },
      "required": ["reason", "amount"]
    }
  },
  "responses": {
    "200": {...}
  }
}

Agentはテストケースを生成します：

{
  "name": "Create refund - success",
  "endpointId": "ep-001",
  "request": {
    "path": "/api/orders/order-123/refund",
    "body": {
      "reason": "Customer request",
      "amount": 99.99
    }
  },
  "assertions": [
    {
      "subject": "responseJson.status",
      "comparator": "equal",
      "target": "processed"
    }
  ]
}

書き込む前に検証：

apidog cli-schema validate test-case-create --file ./test-case-create.json

CLI検証結果：

{
  "success": true,
  "agentHints": {
    "summary": "テストケースの構造は有効です。",
    "nextSteps": [
      "Apidogでテストケースを作成する。",
      "作成されたテストケースを読み戻して確認する。",
      "必要に応じてアサーションを追加する。"
    ]
  }
}

テストケースの作成：

apidog test-case create --project <projectId> --file ./test-case-create.json

CLI出力：

{
  "success": true,
  "data": {
    "id": "tc-001",
    "name": "Create refund - success"
  },
  "agentHints": {
    "summary": "テストケースが正常に作成されました。",
    "nextSteps": [
      "テストケースtc-001を読み戻してアサーションを確認する。",
      "GET /refund/{refundId}のテストケースを作成する。",
      "完全な返金フローのテストシナリオを構築する。"
    ]
  }
}

ステップ3: 完全なフローのテストシナリオ

PRDに基づいて、完全なビジネスフローは次のとおりです：

注文の作成 → 支払い → 返金 → 返金ステータスの照会

Agentはシナリオを生成します：

{
  "name": "Order Refund Complete Flow",
  "steps": [
    { "type": "case", "caseId": "tc-create-order" },
    { "type": "case", "caseId": "tc-pay" },
    { "type": "case", "caseId": "tc-001" },
    { "type": "case", "caseId": "tc-get-refund" }
  ]
}

書き込む前に検証：

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

シナリオの作成：

apidog test-scenario create --project <projectId> --file ./scenario-update.json

ステップ4: 検証の実行

テストケースとシナリオの準備が整ったら：

apidog run --project <projectId> \
  --test-scenario scenario-001 \
  --environment env-production \
  -r "cli,html,junit" \
  --out-dir ./apidog-reports

CLI出力：

{
  "success": true,
  "stats": {
    "total": 4,
    "passed": 4,
    "failed": 0
  },
  "reportFiles": {
    "cli": "./apidog-reports/cli-report.txt",
    "html": "./apidog-reports/report.html",
    "junit": "./apidog-reports/junit.xml"
  },
  "agentHints": {
    "summary": "すべてのテストに合格しました。4つのステップが正常に実行されました。",
    "nextSteps": [
      "詳細な結果についてはHTMLレポートを確認する。",
      "失敗が発生した場合は、CLIのエラー詳細を使用してデバッグする。",
      "このテストをCIパイプラインに統合する。"
    ]
  }
}

完全な連鎖

すべての要素が接続されました：

すべてが検証可能で追跡可能です。

フロー全体でのagentHints

agentHintsが各遷移をどのようにガイドするか注目してください：

Agentは次に何をすべきかを推測する必要がありません。

比較：このタスクにおけるMCPとCLI + SKILL

次は何？

この実践的な例は、CLI + SKILLが実際のワークフローでどのように機能するかを示しています。

しかし、これらすべての根底にはCI/CDの互換性があります。

パート8のAgentツールにとってCI/CD互換性が不可欠な理由では、apidog runがCIパイプラインとAI Agentの両方に役立つ理由、そしてその二重の目的が持続可能なツール設計にとって重要である理由を探ります。

主要なポイント

• 完全なワークフロー：PRD → OpenAPI → インポート → テストケース → シナリオ → 検証
• 各ステップにはCLIコマンド + 検証 + agentHintsがあります
• ステップのインポート + 読み戻しは、シナリオを手書きするよりも安全です
• --with-case-detailは更新のための実用的な構造を提供します
• agentHintsがすべての遷移をガイドします
• すべてが検証可能で追跡可能です

Apidogをダウンロードして、1つのワークスペースでAPIの設計、モック、テスト、ドキュメント化を行いましょう。 コマンドラインAPIテスト、CI自動化、AI Agentワークフロー向けのApidog CLIについてさらに詳しく学びましょう。