Swag Go API 文档生成

要解决的问题

Go 后端项目里，API 文档往往散落在代码注释、wiki 和口头约定中。等到客户端要对接、或者发版前需要做接口评审时，才发现文档与实际路由、参数已经对不上。Swag 的思路是把文档绑定到源码上：在 handler 上方直接写声明式注释，工具扫描源码树后生成 Swagger 2.0 文档，文档与代码始终放在一起演进。本技能面向的场景是：当 agent 需要在文档评审、客户端生成或发版检查之前，把 Go handler 上的注释变成一份可评审的 Swagger 2.0 文档时，按正确流程完成这件事。

技能如何工作

核心流程分三步：

• 定位入口：扫描带声明式注释的 Go API 源码树，确定承载一般信息（general API info）的入口文件，通常是 main.go。
• 解析注释：读取 handler 上方的 // @ 注释，覆盖路由、参数、响应结构与扩展字段。扩展字段的键必须以 x- 开头，且只能取 JSON 值，例如 // @x-example-key {"key": "value"}。
• 生成并接入：生成文档后，必须 import 生成的 docs/docs.go，让对应配置完成 init。若一般信息不在 main.go 中，用 -g 标志显式指定入口文件。

适用边界与注意点

• 仅覆盖 Go 生态的 Swagger 2.0 文档生成，不是 OpenAPI 3.x 的完整方案。
• 输出质量取决于注释质量：注释缺失或与实现不一致时，生成的文档同样缺失或失真，工具不会替你校验实现。
• 注释格式遵循上游声明式注释规范，团队需要自行约定书写风格与维护责任。