generate-api-collection

生成 API 集合

核心原则： 每个 API 接口面（Rails 应用或引擎）都有一个 API 集合文件，并且该文件始终与其端点保持同步。

规则速览

方面	规则
时机	创建或修改任何 REST API 端点（路由 + 控制器操作）时，创建或更新集合
格式	Postman Collection JSON v2.1（schema 或 info.schema 引用 v2.1）
位置	每个应用或引擎一个文件 — docs/api-collections/<app-or-engine-name>.json 或 spec/fixtures/api-collections/；如果集合文件夹已存在，则更新现有文件
语言	所有请求名称、描述和变量名称都必须使用英语
变量	使用 {{base_url}} 作为基础 URL，以便集合适用于不同环境
每个请求	方法、URL、标头、正文、描述和测试脚本（例如，pm.response.to.have.status(200)）
文件夹	使用嵌套的 item 数组将相关端点分组到文件夹中
例外	GraphQL 端点 — 请改用 implement-graphql

硬性门槛

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. 使用 {{base_url}} 作为基础 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，并在提交前修复所有错误（参见“硬性门槛”）

扩展资源

仅在需要具体集合示例时加载：

• EXAMPLES.md — Postman v2.1 多端点集合示例。

集成

技能	关联时机
create-engine	引擎公开 HTTP 端点时
version-api	新版本需要更新集合时