用途:当创建或修改 Rails 应用或引擎中的 REST API 端点(路由加控制器动作)时,用于创建或更新对应的 API 集合文件,否则接口流程无法被测试。GraphQL 端点不适用,应改用 implement-graphql。
主要能力:为每个应用或引擎维护单一 API 集合文件,格式为 Postman Collection JSON v2.1,使用 {{base_url}} 变量以适配多环境;按嵌套 item 数组把相关端点分组为文件夹;每个请求包含方法、URL、请求头、请求体、描述以及至少一个基础测试脚本(如状态码检查)。所有请求名称、描述、变量名要求使用英文。集合文件位置为 docs/api-collections/<app-or-engine-name>.json 或 spec/fixtures/api-collections/;若集合文件夹已存在则更新已有文件。
使用方式:先创建或打开对应集合 JSON 文件;按用途将端点分组到文件夹;用 {{base_url}} 作为基础地址;为每个请求补齐方法、URL、头、体、描述和测试脚本;随后用 python -m json.tool collection.json 或 jq . collection.json 校验 JSON 语法并修复报错直到命令正常退出;确认集合可被 Postman 等兼容客户端无错误导入,并核对新增或变更端点均已覆盖且 {{base_url}} 使用一致。生成 POST/PUT 请求时要包含 Content-Type 与示例请求体,避免开箱即用失败。
适用场景与限制:适用于 Rails 应用或引擎的 REST 接口文档与手测集合维护,可与 create-engine(引擎暴露 HTTP 端点时)、version-api(新版本需更新集合)配合。资料未提供该技能的安装命令、依赖版本、价格、平台兼容细节或效果数据。集合结构要求包含 info 块、嵌套 item 数组和 event 脚本,变量中定义 base_url。资料中完整示例代码较长,此处不逐段抄录,仅保留必要命令与规则。