SuperAPI AI 工具集

collection-schema-v3

编程与开发

查看项目

更新于 11-11 03:27

技能介绍

该技能为 Postman Claude Code 插件提供 Git 原生 v3 集合文件格式的参考说明,主要用途是指导如何以“一实体一文件”的方式组织和读写 postman/collections/ 下的集合内容。

主要能力与结构:

一、整体目录。v3 集合是一棵目录树,位于 postman/collections/ 下。每个请求、每个文件夹的元数据、每个保存的示例都是独立文件,不存在单一的 collection.json。postman/collections/ 下的每个文件夹都是一个集合,可包含子文件夹与请求。文件夹或集合可拥有 .resources/ 目录,用于存放该作用域的元数据;collection/folder 自身的元数据放在 .resources/definition.yaml,请求示例放在 .resources/<request-name>.resources/examples/。文档强调 .resources/ 目录只放元数据,绝不能把请求文件放进去。

二、定义文件 .resources/definition.yaml。可选元数据,字段包括:$kind 必填且固定为 "collection"(文件夹定义也用此值);name 可选,默认取文件系统文件夹名;description 可选;variables 为 {key, value, description?, disabled?} 数组,value 必须为字符串,disabled 为布尔;auth 为单个 {type, credentials:[{key,value},...]} 或用于 multiAuth 的数组 [{id, name, type, credentials, rules?}, ...];scripts 为 {type, code, language:"text/javascript"} 数组,type 取值 http:beforeRequest、http:afterResponse、graphql:beforeQuery、graphql:afterResponse、grpc:beforeInvoke、grpc:onIncomingMessage、grpc:afterResponse;order 为数字,用于文件夹排序。

三、HTTP 请求文件 *.request.yaml。$kind 必填为 "http-request";name 可选(仅当与文件名主干不同时才写);order 为数字,仅作相对比较,建议按 1000 的倍数留出间隔,避免插入时重编号所有同级文件;url 为字符串,支持 {{varName}} 变量语法;method 为 GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS;headers、queryParams 为 {key, value, description?, disabled?} 数组;pathVariables 为 {key, value, description?} 数组;body 为 {type, content},只要存在 body 就必须有 type,类型包括 json、formdata、urlencoded、text、xml、html、javascript、file、none,其中 json/text/xml/html/javascript 的 content 为字符串,formdata 的 content 为 {key, type:"text"|"file", value 或 src, contentType?, description?} 数组,urlencoded 的 content 为 {key, value, description?} 数组;auth 为 {type, credentials};settings 可含 protocolVersion、strictSSL、followRedirects、maxRedirects、disabledSystemHeaders;scripts 为 {type:"beforeRequest"|"afterResponse", code, language:"text/javascript"} 数组;examples 可选,为指向示例目录的相对路径,如 ./.resources/<request-name>.resources/examples/。

四、HTTP 示例文件 *.example.yaml。$kind 必填为 "http-example";name 可选;request 含 {url, method};response 含 {statusCode, statusText, headers:[{key,value}], body:{type, content}};order 可选。文档指出,保存的示例是集合 AI 就绪检查所关注的内容,即使结构完全合法,没有示例的请求在智能体消费方面得分更低。

五、环境文件 postman/environments/*.yaml。name 必填;values 为 {key, value:字符串, enabled:布尔, type:字符串如 "default"} 数组,value 必须为字符串。

六、YAML 规则。无效 YAML 会以难以排查的方式静默破坏解析,建议拿不准就加单引号:含 {{variables}} 的值必须单引号包裹,如 url: '{{base_url}}/users';含 : # & * ! [ ] { } > | 等字符的值需单引号,如 name: 'Health check: v2';多行内容(JSON 请求体、脚本、查询)使用 |- 块标量;本意为字符串却形似布尔/数字的值需加引号,如 value: "true"、value: "123";order 必须为裸数字,不得加引号;文件路径用单引号且只用正斜杠。

七、命名规则。请求文件名主干(.request.yaml 之前)不得包含 / \ : * ? " < > |,需替换为 -;仅当 name 与文件名主干不同时才在文件中写 name(例如文件名为 Health-check.request.yaml 而 name 为 'Health/check',因文件名无法含 /);同一目录内文件名必须大小写不敏感地唯一。

八、示例。文档给出“bookstore api”的完整示范,包括 GET 全部书籍、按 :id 获取书籍(含 pathVariables)、新增书籍(含 JSON body 块标量与 Content-Type 头)三个请求文件,以及 .resources/definition.yaml 中 $kind、name 和 base_url 变量的写法。

适用场景:需要手工编写、审查或校验 Postman v3 Git 原生集合文件的人士与智能体,尤其是希望集合便于智能体消费、需要规范 YAML 与目录结构时。

限制:该参考仅覆盖 HTTP。使用 GraphQL、gRPC、WebSocket、Socket.IO、MQTT、MCP 或 LLM 请求的集合需查阅其它协议参考文档,且这些协议的 schema 与 HTTP 存在实际差异(如 gRPC 的 methodDescriptor、LLM 的 userPrompts/systemPrompts),不可从 HTTP 形状类推。资料未提供价格、平台支持范围或效果保证等信息。