代码自动生成 OpenAPI 接口文档

要解决什么问题

接口实现写在 Controller/Service 里之后，文档往往滞后：手写 OpenAPI/Swagger 容易漏字段、路径与真实代码不一致，再同步到 Apifox、Postman 又要重复维护。这个技能面向「新端点已经能编译通过」的时刻，把文档生成从事后补作业变成实现流程里的一步。

技能如何工作

触发场景是：新建或改完 API 端点（Controller/Service 层），且工程已成功编译之后。技能会按 OpenAPI 3.1 规范产出描述，并采用 每个 API 端点对应一个文件 的粒度，便于按路由拆分、评审和版本管理。

生成物是标准 OpenAPI，而不是某个工具的私有格式，因此可以导入 Apifox、Postman 等支持 OpenAPI 的生态，用同一份契约做调试、Mock 或协作。

适用边界与注意点

• 它解决的是文档契约的生成与对齐，不替代你在代码里对鉴权、错误码、分页等业务约定的设计。
• 应在实现稳定且编译通过后再生成，避免半成品接口反复改 spec。
• 若项目已有全局 openapi.yaml 合并策略，需要自行约定如何把「每端点一文件」并入仓库的文档布局。