swag init 找不到 handler 是因函数未被显式引用或注释不规范；@Param 需匹配路由参数名、in 类型及结构体导出；exit status 2 多因注释语法错误；Swagger UI 404 常因静态路由配置不当。
swag init 为什么找不到 handler 函数
常见现象是执行 swag init 后生成的 docs/docs.go 里没接口，或 swagger.json 空空如也。根本原因不是代码写得不对，而是 swag 默认只扫描当前目录及其子目录下带 // @Summary 这类注释的函数——但前提是这些函数得被「显式引用」在 main 包的初始化路径里。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 确保你的路由注册代码（比如
r.GET("/user", userHandler)）和 handler 函数（userHandler）都在 swag 扫描范围内；如果 handler 在独立包里，main 包必须 import 该包（哪怕没直接调用，也要让 go list 能发现它） - handler 函数签名必须是标准 HTTP handler 类型：
func(w http.ResponseWriter, r *http.Request)或 gin 的func(*gin.Context)，其他签名（如返回 error、带 context.Context 参数）不会被识别 - 别把注释写在函数声明前多于一行空白处——
swag解析器对空行敏感，紧贴函数声明上方才稳定生效
gin 框架下 @Param 注解怎么写才不报错
写 // @Param 时最常踩的坑是字段名、数据类型、位置（in）三者不匹配，导致生成的 swagger 文档字段丢失或 UI 报错 “schema not found”。尤其 gin 的 URL 参数（:id）、查询参数（?page=1）、请求体（POST /user）对应不同写法。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 路径参数必须写
in: path，且name要和路由定义完全一致：比如路由是/user/:uid，注释就得是// @Param uid path string true "用户ID" - 查询参数用
in: query，无需加冒号，name就是 URL 中的键名，如page、sort - 请求体（
POST/PUT）统一用in: body，name固定写body，后面跟结构体名，例如// @Param body body models.User true "用户数据"，且该结构体必须已导出、有 JSON tag
swag 命令生成 docs 失败：exit status 2 是什么问题
swag init 返回 exit status 2 不是 Go 编译错误，而是 swag 自身解析失败。最常见原因是注释语法非法，比如少写了引号、漏了必填字段、用了不支持的类型别名，或者结构体嵌套过深导致反射崩溃。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 先运行
swag init -v查看详细错误位置，通常会指出第几行注释格式不对 - 避免在
@Success或@Failure中直接写未导出结构体（如internal.User），swag 只能处理导出（首字母大写）且可被反射读取的类型 - 别用
map[string]interface{}作响应体——swag 无法推导其字段，改用明确结构体；若真要泛型响应，用struct{ Data interface{} }并配@Schema注释说明
生成的 Swagger UI 打不开或接口 404
生成文档后，启动服务却访问 /swagger/index.html 一片空白，或点接口发送请求返回 404，问题往往不在 swag 本身，而在 Web 框架的静态文件路由配置和路径挂载方式。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 确认是否正确导入并初始化了
docs.SwaggerInfo：必须在 main 包中执行docs.SwaggerInfo.Title = "My API"类似赋值，否则docs/docs.go不会被编译进二进制 - gin 用户注意：不能只写
r.StaticFS("/swagger", http.Dir("./docs"))，必须配合swaggerFiles—— 正确姿势是r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - 如果你用的是自定义端口或反向代理（如 Nginx），检查是否把
/swagger/路径完整透传，有些代理会截掉末尾斜杠导致 JS 加载失败
真正麻烦的不是生成，是注释和代码结构的耦合度——改个字段名，忘了同步更新 @Schema 注释，前端就收不到字段。这种隐式依赖没法靠工具校验，只能靠团队约定和 Code Review 卡住。
