技能介绍

问题在哪

REST 接口一旦散落在 Express 路由、FastAPI 装饰器或口头约定里，OpenAPI / Swagger 文档很容易滞后：手写 YAML 容易漏端点、错 required，版本混用（3.x 与 2.0）时 components 与 definitions 结构也对不上。你需要的是一份完整且可校验的规范，而不是带 # TODO 的骨架。

技能如何工作

技能按固定流程推进：先收集或从上下文推断 OpenAPI 3.x / Swagger 2.0、输出 YAML 或 JSON、API 用途、端点、认证与通用模型；若你已给出代码，会从框架路由里自动提取端点，不再重复追问。

构建阶段遵循对应版本结构，并强调工程化细节：

复用模型一律用 $ref，并为 schema / 响应提供 example
在 components/responses 里集中 401、404、500 等，减少重复
按清单核对 operationId、4xx/5xx、securitySchemes 与根级 tags

交付时在代码块给出完整规范，附端点摘要表；可选继续对接 Spectral 校验、Prism 模拟或 SDK 存根。规范定稿后会询问是否基于同一文档生成 API 测试用例（需另装对应技能）。

适用边界

它擅长生成与补全规范，不能替代你对业务语义、权限边界的最终裁定。从代码推断的类型与字段可能偏保守，复杂分页、HATEOAS、webhook 等应结合技能内 reference 模式人工核对；查询参数里的 API Key 等敏感设计文档里会明确标注风险。

截图预览

使用场景

Express/Fastify 路由已上线却缺文档，需从 `.get/.post` 等调用提取 paths 并输出可校验的 OpenAPI 3.x YAML。
产品用自然语言说明了资源、端点与 JWT 认证，编码前要先产出带 `securitySchemes` 与 tags 的完整规范骨架。
仓库里只有缺 paths 或 schemas 的半成品规范，要在不覆盖现有 components 的前提下合并新端点并补全 `$ref`。
FastAPI/Spring 控制器与 DTO 已在代码里，需要把 Pydantic/请求体映射成 JSON Schema，并统一 401、404、500 等响应引用。