swaggo/swag 通过解析 Go 源码注释自动生成 OpenAPI 文档，需严格遵循注释语法（如 @Summary、@Success、@Router），结构体加 swagger:model 标签，参数显式声明，配合 gin-swagger 可嵌入交互式 UI；CI/CD 中须强制校验 docs/swagger.json 一致性以防文档滞后。
用 swaggo/swag 自动生成 Go 接口文档
Go 项目里手写 OpenAPI（Swagger）文档既易出错又难维护，swaggo/swag 是目前最主流的方案：它通过解析源码中的注释，直接生成 swagger.json，零运行时开销，且与 Gin/Echo/Chi 等框架天然兼容。
关键前提是：注释必须严格遵循特定语法，否则 swag init 会静默跳过或报错。
- 所有 HTTP handler 函数必须有
// @Summary、// @Success、// @Router三类基础注释 - 结构体字段需加
// swagger:xxx标签（如// swagger:model）才能被识别为 schema - 路由路径中带参数（如
/users/{id}）时，// @Param id path int true "user ID"必须显式声明 -
swag init默认只扫描当前目录及子目录，跨模块需用-g指定入口文件，用-o指定输出目录
Gin 项目中嵌入 Swagger UI 页面
生成 docs/ 目录后，只需几行代码就能在开发环境暴露交互式文档页面。注意：不要在生产环境启用，避免暴露内部接口细节。
import "github.com/swaggo/gin-swagger"
<p>// 在 router 初始化后添加
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))访问 http://localhost:8080/swagger/index.html 即可查看。常见问题：
立即学习“go语言免费学习笔记（深入）”；
- 页面白屏 → 检查
docs/swagger.json是否存在、是否可被 HTTP 访问（路径是否拼错） - 接口列表为空 →
swag init未成功执行，或 handler 函数没加@Router注释 - 请求无法发送 → 后端未配置 CORS，可在 dev 环境临时加
router.Use(cors.Default())
处理复杂响应结构（如泛型封装、嵌套 error）
Go 没有运行时反射泛型类型，swag 无法自动推导 Result[T] 中的 T。必须手动指定响应 schema：
// @Success 200 {object} model.Result{data=model.User} "user info"
func GetUser(c *gin.Context) {
c.JSON(200, model.Result[model.User]{Data: user})
}其中 model.Result 需标注为模型：
type Result[T any] struct {
Code int `json:"code"`
Msg string `json:"msg"`
Data T `json:"data"`
}
// swagger:model
type User struct {
ID int `json:"id"`
Name string `json:"name"`
}其他易漏点：
- 错误响应（如 400/500）要用
// @Failure显式声明，否则 UI 不显示错误示例 - 数组响应写法是
{array}model.User，不是[]model.User - query/body 参数若为指针或自定义类型，需额外用
// @Param xxx body model.Req true "request"描述
CI/CD 中自动化更新文档
文档滞后是最大风险。建议在 PR 流程中加入校验步骤：提交前强制生成并 diff docs/swagger.json，不一致则拒绝合并。
Git Hook 示例（.git/hooks/pre-commit）：
#!/bin/sh swag init -o docs --quiet if ! git diff --quiet -- docs/swagger.json; then echo "ERROR: docs/swagger.json is out of date. Run 'swag init -o docs'" exit 1 fi
CI 脚本中也应包含相同逻辑，并把 docs/ 提交进仓库——Swagger UI 依赖这些静态文件，不能只靠构建时生成。
真正麻烦的是接口变更后忘记改注释，工具不会报错，但文档就和实际行为对不上了。这事只能靠 Code Review 和自动化 diff 卡住，没有银弹。
