Go语言用swag工具通过扫描带特定前缀的Go注释生成Swagger文档，需正确安装、配置全局注释、接口注释（@Summary和@Router必填）、结构体引用及集成UI。
Go语言做Swagger文档生成，核心就一条路：用 swag 工具扫描代码注释，自动生成 swagger.json 和 UI 页面。不是写 YAML 再生成代码，也不是靠运行时反射猜接口——它依赖你手写的、带特定前缀的 Go 注释。
怎么装 swag 并确认它真能用
swag 是命令行工具，不是库，装错位置或没进 $PATH 就会报 command not found。别用 go get（已弃用），必须用 go install：
go install github.com/swaggo/swag/cmd/swag@latest- 检查
$GOBIN是否在$PATH中：echo $PATH | grep "$(go env GOPATH)/bin" - 运行
swag -v，输出类似swag version v1.17.2才算成功；如果报cannot find package，大概率是 Go Proxy 没配，加一句go env -w GOPROXY=https://goproxy.cn,direct
注释写在哪？哪些标签不能少
注释必须写在 HTTP handler 函数正上方，且函数得被 swag init 扫到（默认只扫 main.go 所在目录及子目录）。漏掉 @Summary 或 @Router，该接口直接不出现在文档里。
-
@Summary和@Router是硬性要求，缺一不可 -
@Param类型要写对：路径参数用path，查询参数用query，请求体用body -
@Success和@Failure的结构体类型必须可被解析（不能是未导出字段、不能跨 module 未加// @modelsPackage） - 示例：
// @Summary 获取用户列表 // @Description 分页查询用户，支持按邮箱模糊匹配 // @Tags users // @Accept json // @Produce json // @Param page query int false "页码" default(1) // @Param limit query int false "每页数量" default(10) // @Success 200 {array} models.User // @Failure 400 {object} models.ErrorResponse // @Router /api/v1/users [get] func ListUsers(c *gin.Context) { ... }
swag init 总失败？先看这几个常见卡点
swag init 报错不报具体文件，容易让人瞎试。最常卡在三类地方：
立即学习“go语言免费学习笔记（深入）”；
- 找不到
@title等全局注释：确保main.go（或你指定的-g文件）顶部有完整配置，比如// @title 用户服务 API，否则提示failed to parse general API info - 结构体引用失败：如果
@Success 200 {object} models.User中的models.User在另一个 module，swag默认不跨 module 解析，需加// @modelsPackage github.com/yourname/project/models - 字段名大小写混乱：默认按
camelcase解析 JSON tag，但如果你结构体用的是snake_case（如user_name string `json:"user_name"`），得加-p snakecase参数，否则文档里字段名变成userName而不是user_name - 命令示例：
swag init -g ./cmd/api/main.go -d ./internal/handler -o ./docs -p snakecase
集成 Swagger UI 到 Gin（或其他框架）
生成完 docs/ 目录后，只是有了静态文件，还没网页。需要显式导入生成的 docs 包，并挂路由：
- 先在 main.go 所在目录执行
swag init，确保docs/docs.go存在 - 导入包：
import _ "your-project-path/docs"（注意下划线，仅触发 init） - Gin 示例：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - 启动服务后访问
http://localhost:8080/swagger/index.html—— 如果空白，大概率是没 importdocs包，或者路径写错了（your-project-path必须和go.mod里 module 名完全一致）
最容易被忽略的是：每次改了注释，必须重新跑 swag init；它不会监听文件变化。还有就是 docs/docs.go 一旦生成，就和源码解耦了，删掉它再 init 才能生效——很多人改完注释刷新页面没变，其实是忘了这步。
