Api To Openapi

---
name: api-to-openapi
description: >
  将自然语言接口描述、接口文档、参数表格或支持的后端代码转换为标准 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.
---

# 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` |

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