Api to openapi

API to OpenAPI

目标

把自然语言描述、接口文档或后端代码中的 API 信息，统一转换为可导入平台的接口文档。

本 skill 只负责：

1. 识别输入来源和接口边界
2. 抽取路径、方法、参数、响应、鉴权、示例
3. 生成并校验 OpenAPI 3.0.3 JSON
4. 在用户明确需要时生成平台兼容产物，如 Postman Collection

本 skill 不负责直接写入 Postman、Apifox、ApiPost 等平台。若用户要求“直接导入/同步到平台”，先生成可导入产物，再说明需要由独立 MCP/API 工具完成平台写入。

处理流程

1. 判断用户意图

仅在用户要从已有接口信息生成或转换“可导入接口文档”时继续。典型触发：

• “把这段接口文档转成 OpenAPI/Swagger”
• “生成可导入 Apifox/Postman/ApiPost 的接口”
• “把这段 Laravel/PHP 接口代码导出成接口文档”
• “根据这段描述生成可以调试的 API 文档”

不要在这些场景使用本 skill：

• 用户只是要实现一个接口
• 用户只是要调试请求失败
• 用户只是要 review API 代码质量
• 用户要求把结果直接写进平台账号或项目

2. 识别输入类型并加载适配器

从上到下首次命中即停止：

优先级	识别特征	输入类型	加载
1	<?php / Route:: / $request-> / ->validate( / $_POST	PHP 代码	references/lang-php.md
2	Markdown 参数表格、接口说明块、自然语言描述中包含方法/路径/参数/响应	文档或描述	references/doc-markdown.md
3	@app.route / def + request / FastAPI / Flask	Python 代码	references/lang-python.md
4	app.get( / app.post( / @Controller / @Get( / express	Node.js 代码	references/lang-nodejs.md
5	func + gin.Context / r.GET( / echo.Context	Go 代码	references/lang-golang.md
6	均不匹配	未知	先询问用户语言/框架或让用户整理为文档格式

完整阅读匹配到的适配器文件。适配器负责框架识别、参数提取、类型映射、鉴权判断和响应提取。

3. 生成 OpenAPI 主产物

始终把 OpenAPI 3.0.3 JSON 作为主产物。生成前完整阅读 references/openapi-output.md。

核心要求：

• 使用 openapi: "3.0.3"
• paths 中的路径必须以 / 开头
• HTTP method 使用小写键：get / post / put / patch / delete
• GET、DELETE 和 path/query/header/cookie 参数使用 parameters
• POST、PUT、PATCH 的 body 参数使用 requestBody
• 文件上传使用 multipart/form-data
• 多接口合并到同一个 paths 对象
• 不要编造无法从输入推断的信息；无法确定时用 "TODO" 或在 description 中说明

4. 处理平台目标

如果用户提到 Postman、Apifox 或 ApiPost，完整阅读 references/platform-targets.md。

默认策略：

• Apifox：输出 OpenAPI JSON
• ApiPost：输出 OpenAPI JSON
• Postman：默认输出 OpenAPI JSON；用户明确要求 Postman Collection、环境变量、测试脚本或预请求脚本时，额外输出 Postman Collection v2.1 JSON

不要生成 Apifox/ApiPost 私有格式，除非用户提供稳定的目标 schema 或明确要求并提供平台格式样例。

5. 校验输出

输出前执行人工校验：

1. JSON 必须可解析，无注释、无尾逗号、无 Markdown 混入 JSON 代码块内部
2. OpenAPI 必须包含 openapi、info、paths
3. 每个 operation 必须包含 summary、responses
4. 每个 request schema 的 required 只包含实际存在的字段
5. 每个 path 参数必须同时出现在路径模板和 parameters
6. 有鉴权时声明 components.securitySchemes 并在 operation 中引用
7. 导入型输出不要在 JSON 前后混入接口清单；接口清单放在单独说明里

字段名语义兜底

当适配器无法确定字段类型时，按字段名推断：

字段模式	OpenAPI 类型
*_id / *_no / *_num / page / limit / offset / size / count / total	integer
*_at / *_time / created_* / updated_* / *_timestamp	string, format: date-time
*_date	string, format: date
price / amount / rate / *_fee / *_money / *_price / *_cost	number
is_* / has_* / enable_* / *_flag	boolean
*_list / *_ids / *_arr / items / tags / categories	array
其他	string

字段名保持原样，不做风格转换。