generate-api-collection

API コレクションの生成

基本原則： すべての API サーフェス（Rails アプリまたはエンジン）には、エンドポイントと常に同期する API コレクションファイルが 1 つあります。

ルールの概要

項目	ルール
タイミング	REST API エンドポイント（ルート＋コントローラーアクション）を作成または変更する際に、コレクションを作成または更新します
形式	Postman Collection JSON v2.1（schema または info.schema が v2.1 を参照）
保存場所	アプリまたはエンジンごとに 1 ファイル — docs/api-collections/<app-or-engine-name>.json または spec/fixtures/api-collections/。コレクションフォルダーがすでに存在する場合は、既存のファイルを更新します
言語	リクエスト名、説明、変数名はすべて英語にする必要があります
変数	さまざまな環境でコレクションを使用できるよう、ベース URL には {{base_url}} を使用します
リクエストごと	メソッド、URL、ヘッダー、本文、説明、テストスクリプト（例：pm.response.to.have.status(200)）
フォルダー	ネストした item 配列を使用して、関連するエンドポイントをフォルダーにまとめます
例外	GraphQL エンドポイントには、代わりに implement-graphql を使用します

HARD-GATE

When you create or modify a REST API endpoint (new or changed route and controller action),
you MUST also create or update the corresponding API collection file so the
flow can be tested. Do not leave the collection missing or outdated.

Each request MUST include a description and at least one basic test script (e.g. status code check).

EXCEPTION: GraphQL endpoints — use implement-graphql instead.

基本的な手順

1. 対応する API コレクション JSON ファイルを作成するか、開きます。
2. ネストした item 配列を使用して、関連するエンドポイントをフォルダーにまとめます。
3. ベース URL には {{base_url}} を使用します。
4. 各リクエストにメソッド、URL、ヘッダー、本文、説明、テストスクリプトを追加します。
5. JSON の構文が正しいことを検証します。
   • python -m json.tool collection.json または jq . collection.json を実行します。どちらも無効な JSON の場合はエラーを出力します。
   • 無効な場合：報告されたエラーを修正し、コマンドがエラーなく終了するまで再実行します。
6. 互換性のある API クライアント（例：Postman）にコレクションをエラーなくインポートできることを確認します。
7. 新規または変更されたすべてのエンドポイントが含まれていること、および {{base_url}} が一貫して使用されていることを確認します。

コレクションの構造（Postman v2.1）

コレクションに info ブロック、フォルダー（ネストした item 配列）、event スクリプトが含まれていることを確認します。

{
  "info": {
    "name": "Products API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Products",
      "item": [
        {
          "name": "List products",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{base_url}}/api/v1/products",
            "description": "Returns a list of all products in the catalog."
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": ["pm.test('Status code is 200', () => { pm.response.to.have.status(200); });"],
                "type": "text/javascript"
              }
            }
          ]
        }
      ]
    }
  ],
  "variable": [
    { "key": "base_url", "value": "http://localhost:3000" }
  ]
}

よくある間違い

間違い	実際には
POST/PUT に Content-Type または本文がない	すぐにリクエストを実行できるよう、ヘッダーと本文の例を含めます
生成後の検証を省略する	コミット前に jq . または python -m json.tool を実行し、エラーを修正します（HARD-GATE を参照）

関連リソース

具体的なコレクション例が必要な場合にのみ読み込みます。

• EXAMPLES.md — Postman v2.1 の複数エンドポイントコレクションの例。

連携

スキル	連携するタイミング
create-engine	エンジンが HTTP エンドポイントを公開する場合
version-api	新しいバージョンでコレクションの更新が必要な場合