api-schema-parser

name api-schema-parser description 接口定义解析器技能。专门负责处理并解析来自不同来源、不同格式的接口定义数据（Swagger/OpenAPI、Postman集合、HAR抓包、YApi/Apifox导出文档、纯文本描述），统一转换成结构一致、格式标准、可被后续环节直接复用的结构化接口数据。自动识别输入源类型，提取接口核心信息、解析参数与响应、识别隐性业务规则，输出标准化 api_definitions.yaml/json。 API Schema Parser - 接口定义解析器 概述 本技能扮演接口架构分析专家角色，核心能力是将来自不同来源、不同格式的接口定义数据，统一转换成结构一致、格式标准、可被后续所有环节直接复用的结构化接口数据。无论输入是 Swagger/OpenAPI 规范文件、Postman 集合导出、HAR 抓包文件、YApi/Apifox 导出文档，还是纯文本描述，都能通过本技能完成标准化清洗与结构化输出，为后续脚本生成、数据构造、场景分析提供统一、可靠的输入基础。 核心流程： 输入（Swagger/Postman/HAR/YApi/纯文本/混合） ↓ Step 1: 自动识别输入源类型 ↓ Step 2: 匹配对应解析规则，提取接口核心信息 ↓ Step 3: 解析参数（Path/Query/Header/Body） ↓ Step 4: 解析响应（成功/异常响应体） ↓ Step 5: 识别隐性业务规则 ↓ Step 6: 输出标准化 api_definitions.yaml/json 触发条件 以下场景自动触发本技能： 用户提供 Swagger/OpenAPI JSON/YAML 文件，要求解析接口定义 用户提供 Postman 集合导出文件（.json/.postman_collection.json） 用户提供 HAR 抓包文件（.har） 用户提供 YApi/Apifox 导出的接口文档 用户提供纯文本格式的接口描述 用户要求"解析接口""标准化接口定义""提取接口信息""接口文档转结构化数据" 用户提及"api-schema-parser""/api_schema_parser" 用户需要为后续测试脚本生成、数据构造、场景分析准备统一的接口数据输入 输入识别 接收以下输入，按优先级处理： 接口定义文件 （必需）：支持以下格式 Swagger 2.0 / OpenAPI 3.x JSON/YAML 文件 Postman 集合 v2.0/v2.1 导出文件 HAR (HTTP Archive) 抓包文件 YApi 导出 JSON 文件 Apifox 导出 JSON/YAML 文件 纯文本 ：自然语言描述的接口信息 业务规则补充说明 （选填）：用户额外提供的业务规则、鉴权方式、限流策略等补充信息 模块归属映射 （选填）：用户提供的模块划分规则，用于对接口进行模块归类 如果用户未提供业务规则补充说明和模块归属映射，对应字段标记为"待补充"，但不影响核心解析流程。 执行流程 Step 1: 自动识别输入源类型 根据文件扩展名、内容结构和关键字段，自动判断输入源类型： 输入源 识别规则 Swagger 2.0 文件含 "swagger": "2.0" 顶层字段，或有 swagger 关键字 OpenAPI 3.x 文件含 "openapi": "3.x.x" 顶层字段 Postman 集合 文件含 "info" + "item" 顶层字段，或 _postman_id 字段 HAR 文件 文件含 "log" 顶层字段，且 log.entries 存在 YApi 导出 文件为 JSON 数组，元素含 path 、 method 、 title 等字段 Apifox 导出 文件含 Apifox 特有的 api 或 apiDetail 结构 纯文本 非 JSON/YAML 格式，或无法匹配上述任何结构 混合输入 ：当用户同时提供多个文件时，逐个识别类型并分别解析，最终合并输出。 Step 2: 提取接口核心信息 参照 references/parsing-rules.md 中对应输入源的解析规则，提取每个接口的核心信息： 字段 说明 必填 api_id 接口唯一标识，格式： {method}_{path} （如 GET_/api/v1/users ） 是 name 接口名称 是 path 接口路径（如 /api/v1/users/{id} ） 是 method HTTP 请求方法（GET/POST/PUT/DELETE/PATCH 等） 是 module 模块归属（基于路径前缀或 tags 推断） 否 description 接口描述 否 deprecated 是否已废弃 否 tags 标签列表（来自 Swagger tags 或推断） 否 模块归属推断规则 ： 优先使用 Swagger/OpenAPI 的 tags 字段 基于路径前缀推断（如 /api/v1/users/* → 用户模块） 基于用户提供的模块归属映射 无法推断时标记为 "未分类" Step 3: 解析参数 对每个接口，解析所有参数并按位置分类： 3.1 参数分类 参数位置 说明 典型场景 Path 路径参数，如 /users/{id} 中的 id 资源标识、ID Query 查询参数，如 ?page=1&size=10 分页、过滤、排序 Header 请求头参数 鉴权 Token、Content-Type、自定义头 Body 请求体参数 JSON 表单、文件上传 3.2 参数字段定义 每个参数必须解析以下字段： 字段 说明 必填 name 参数名称 是 in 参数位置（path/query/header/body） 是 required 是否必填 是 type 数据类型（string/integer/number/boolean/array/object/file） 是 format 格式约束（date-time/email/uri/uuid/int64 等） 否 description 参数描述 否 default 默认值 否 enum 枚举值列表 否 minLength / maxLength 字符串长度约束 否 minimum / maximum 数值范围约束 否 pattern 正则约束 否 example 示例值 否 ref 引用定义（如 $ref 引用的 Schema） 否 3.3 Body 参数深度解析 对于 Body 参数，需递归解析嵌套结构： object 类型 ：递归解析所有属性字段 array 类型 ：解析 items 定义 $ref 引用 ：追踪引用，展开为完整定义 allOf/anyOf/oneOf ：合并或标记为组合类型 文件上传 ：识别 multipart/form-data 和 binary 类型 3.4 参数解析规则（按输入源） 参照 references/parsing-rules.md 中各输入源的具体参数映射规则： Swagger 2.0 ： parameters 数组， in 字段标识位置， schema 引用 Body OpenAPI 3.x ： parameters 数组 + requestBody 对象，使用 content + schema 结构 Postman ：从 item[].request.url.query 、 header 、 body 解析 HAR ：从 request.url 、 request.headers 、 request.postData 解析 YApi ：从 req_query 、 req_headers 、 req_body_type + req_body_other 解析 纯文本 ：基于语义识别参数位置和类型 Step 4: 解析响应 对每个接口，解析成功和异常响应： 4.1 响应字段定义 字段 说明 必填 status_code HTTP 状态码（如 200、400、401、500） 是 description 响应描述 是 content_type 响应内容类型（application/json 等） 否 schema 响应体结构定义 否 example 响应示例 否 4.2 响应体结构解析 递归解析响应体的字段结构，每个字段包含： 字段 说明 必填 field_path 字段路径（如 data.user.name ） 是 type 数据类型 是 description 字段描述 否 required 是否必填 否 enum 枚举值 否 example 示例值 否 nested_fields 嵌套子字段列表（object 类型） 否 4.3 业务错误码映射提取 从响应定义和描述中提取业务错误码映射： error_codes: - code: "USER_NOT_FOUND" http_status: 404 message: "用户不存在" description: "当查询的用户ID不存在时返回" - code: "INVALID_PARAMETER" http_status: 400 message: "参数无效" description: "请求参数校验失败时返回" 提取来源 ： Swagger/OpenAPI 的响应描述和示例 YApi/Apifox 的错误码定义 纯文本中的错误码描述 如果文档中未明确列出错误码，根据 HTTP 状态码和业务场景推断常见错误码 Step 5: 识别隐性业务规则 参照 references/business-rule-patterns.md 中的识别模式，从文档描述和接口定义中提取隐性业务规则： 规则类别 识别模式 典型场景 限流策略 描述中含"限流""频率""QPS""限次"等关键词 同一IP每分钟最多100次请求 加密规则 描述中含"加密""签名""MD5""RSA""AES"等 请求体需RSA加密，签名算法为HMAC-SHA256 鉴权方式 Header 中含 Authorization/Token/X-Auth 等字段 Bearer Token 鉴权，Token 有效期2小时 接口依赖 描述中含"依赖""前置""先调用"等 创建订单前需先获取用户地址列表 数据一致性 描述中含"事务""原子""一致性"等 转账操作需保证原子性 幂等性 描述中含"幂等""重复""去重"等 支付接口需保证幂等，重复请求不重复扣款 数据脱敏 描述中含"脱敏""掩码""隐藏"等 手机号返回 138****5678 格式 并发控制 描述中含"并发""锁""互斥"等 库存扣减需加分布式锁 每个识别出的规则输出为： business_rules: - rule_id: "BR-001" category: "rate_limiting" description: "同一IP每分钟最多100次请求" affected_apis: [ "GET_/api/v1/products" ] source: "swagger_description" confidence: "high" Step 6: 输出标准化文件 6.1 输出格式 根据用户选择输出 YAML 或 JSON 格式，默认输出 JSON。输出文件命名为 api_definitions.json 或 api_definitions.yaml 。 6.2 输出结构 输出结构遵循 references/output-schema.md 中定义的完整 Schema，核心结构如下： # api_definitions.yaml 示例结构 meta: version: "1.0.0" generated_at: "2026-05-26T10:00:00+08:00" source_type: "swagger" # 输入源类型 source_file: "petstore.yaml" # 原始文件名 total_apis: 15 # 接口总数 modules: # 模块列表 - name: "用户模块" api_count: 5 - name: "商品模块" api_count: 10 apis: - api_id: "POST_/api/v1/users" name: "创建用户" path: "/api/v1/users" method: "POST" module: "用户模块" description: "创建新用户账号" deprecated: false tags: [ "用户" , "账号管理" ] parameters: path_params: [] query_params: [] header_params: - name: "Authorization" in: "header" required: true type: "string" description: "Bearer Token" body_params: - name: "username" in: "body" required: true type: "string" minLength: 3 maxLength: 50 pattern: "^[a-zA-Z0-9_]+$" description: "用户名，3-50位字母数字下划线" example: "zhang_san" - name: "email" in: "body" required: true type: "string" format: "email" description: "邮箱地址" example: "zhangsan@example.com" - name: "age" in: "body" required: false type: "integer" minimum: 1 maximum: 150 default: 18 description: "年龄" responses: success: status_code: 200 description: "创建成功" schema: - field_path: "code" type: "integer" description: "业务状态码" example: 0 - field_path: "data.id" type: "string" format: "uuid" description: "用户ID" - field_path: "data.username" type: "string" description: "用户名" errors: - status_code: 400 description: "参数校验失败" error_code: "INVALID_PARAMETER" schema: - field_path: "code" type: "integer" example: 40001 - field_path: "message" type: "string" example: "用户名格式不合法" - status_code: 409 description: "用户名已存在" error_code: "USERNAME_EXISTS" business_rules: - rule_id: "BR-001" category: "authentication" description: "需要管理员权限才能创建用户" affected_apis: [ "POST_/api/v1/users" ] source: "description_inference" confidence: "medium" global_rules: authentication: type: "Bearer Token" header: "Authorization" description: "所有接口需在Header中携带Bearer Token" rate_limiting: default: "100次/分钟/IP" description: "默认限流策略" error_code_pattern: description: "统一错误响应格式" schema: code: "integer - 业务错误码" message: "string - 错误描述" data: "object | null - 错误详情" 6.3 生成脚本调用 将解析结果整理为结构化 JSON 数据 写入临时文件 执行 scripts/schema_parser.py 生成标准化输出文件： # JSON 输出 python3 <skill_path>/scripts/schema_parser.py <input_file> --format json --output api_definitions.json # YAML 输出 python3 <skill_path>/scripts/schema_parser.py <input_file> --format yaml --output api_definitions.yaml # 指定输入类型（跳过自动识别） python3 <skill_path>/scripts/schema_parser.py <input_file> -- type swagger --format json --output api_definitions.json # 混合输入合并输出 python3 <skill_path>/scripts/schema_parser.py <file1> <file2> --format json --output api_definitions.json 将生成的文件交付给用户 纯文本解析策略 当输入为纯文本描述时，按以下策略解析： 识别接口信息 从文本中提取接口信息的关键模式： 信息 识别模式 示例 请求方法 大写的 HTTP 方法名 GET 、 POST 、 PUT 、 DELETE 路径 以 / 开头的 URL 路径 /api/v1/users/{id} 接口名称 方法+路径前的描述文字 "创建用户 POST /api/v1/users" 参数 请求参数段落中的表格或列表 "参数：username（必填，string，3-50位）" 响应 响应段落中的状态码和结构 "成功返回 200 {code: 0, data: {...}}" 参数推断规则 当纯文本中参数信息不完整时，按以下规则推断： 必填性 ：未标注时，Path 参数默认必填，其他默认选填 数据类型 ：根据示例值推断（数字→integer/number，布尔→boolean，数组→array） 约束条件 ：根据描述中的关键词推断（"最大50字符"→maxLength:50，"正整数"→minimum:1）