Api to openapi
A curated collection of production-grade Claude Code skills.
npx -y skills add wunamesst/skills --skill api-to-openapiAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
将自然语言接口描述、接口文档、参数表格或支持的后端代码转换为标准 OpenAPI 3.0.3 JSON， 并在需要时生成 Postman Collection 等平台兼容产物，供 Postman / Apifox / ApiPost 导入后形成可调试接口。 Use when the user asks to generate, export, convert, or validate Swagger/OpenAPI/importable API documentation from existing API descriptions, docs, tables, or code. Do not use merely to implement, call, debug, or review API code. Directly writing/importing into external platforms is outside this skill and belongs to a separate MCP such as api-publish.
SKILL.md
5.1 KB, as published. Nobody here has run it
API to OpenAPI
目标
把自然语言描述、接口文档或后端代码中的 API 信息，统一转换为可导入平台的接口文档。
本 skill 只负责：
- 识别输入来源和接口边界
- 抽取路径、方法、参数、响应、鉴权、示例
- 生成并校验 OpenAPI 3.0.3 JSON
- 在用户明确需要时生成平台兼容产物，如 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. 校验输出
输出前执行人工校验：
- JSON 必须可解析，无注释、无尾逗号、无 Markdown 混入 JSON 代码块内部
- OpenAPI 必须包含
openapi、info、paths - 每个 operation 必须包含
summary、responses - 每个 request schema 的
required只包含实际存在的字段 - 每个 path 参数必须同时出现在路径模板和
parameters - 有鉴权时声明
components.securitySchemes并在 operation 中引用 - 导入型输出不要在 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 |
字段名保持原样，不做风格转换。