Golang怎么用Swagger生成接口文档_Golang如何用swaggo自动生成API文档页面【教程】-Golang-PHP中文网

swag init 报错主因是缺失或格式错误的 // @title 等注释，必须位于 main 包文件中且连续无空行；类型需显式 import、结构体及字段均须首字母大写并带 json tag；docs 目录须与二进制同级；CI 中需指定 -g 入口文件路径。

golang怎么用swagger生成接口文档_golang如何用swaggo自动生成api文档页面【教程】

Swagger 文档生成失败，最常见原因是 swag init 扫不到基础 API 元信息。它不读代码逻辑，只靠特定格式的 Go 注释（叫 “swag comments”）提取标题、描述、版本等——没写或写错位置，就直接报错或生成空文档。

// @title 必须出现在 main 包的某个 .go 文件里（通常是 main.go 或 docs/docs.go），且不能被注释掉、不能在函数体内

注释块必须连续，中间不能有空行，例如：

// @title My API<br>// @version 1.0<br>// @description This is a sample server.

如果用的是模块化项目（如 cmd/xxx/main.go），要确保 swag init 的工作目录包含该文件，或显式指定：swag init -g cmd/myapp/main.go
Go 1.21+ 默认开启 GO111MODULE=on，但 swag 不解析 go.mod，只认文件路径，别指望它自动找入口

写了 // @Success 200 {object} model.User，但网页里 Response Schema 还是空的，大概率是类型没被正确识别——swag 不递归扫描所有包，只看当前文件 + 显式 import 的类型，且要求结构体可导出、字段可导出。

确认 model.User 在当前文件有 import，且 User 首字母大写（否则 swag 当作私有类型跳过）
字段也要首字母大写，且最好加 struct tag，比如 Name string `json:"name"`；没 tag 的字段可能被忽略或显示为 interface{}
如果返回的是指针（*model.User）或切片（[]model.User），注释里也得写全：{object} model.User 和 {array} model.User 含义不同，后者才生成数组示例
嵌套结构体（如 User.Profile *Profile）需要 Profile 类型也在同一包或已 import，否则只显示 object 而无字段细节

调用 httpSwagger.WrapHandler 注册路由后，访问 /swagger/index.html 返回 404，或者页面空白、控制台报 swagger-ui.css:1 Failed to load resource，本质是静态资源没正确挂载。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

确保 swag init 成功执行，生成了 docs/ 目录（含 docs.go、swagger.json 等），这个目录必须和二进制在同一级，否则 httpSwagger 找不到文件
不要手动改 docs/doc.go 里的 docs.SwaggerInfo 路径字段，它只影响 JSON 内容，不影响文件服务路径
使用 httpSwagger.Handler() 时，别漏掉括号：httpSwagger.Handler() 是函数调用，返回 handler；httpSwagger.Handler 是函数地址，会导致 panic
如果你用的是 Gin，注册方式是 r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))；用 net/http 就是 http.Handle("/swagger/", http.StripPrefix("/swagger/", httpSwagger.Handler()))

本地能跑通，CI 流水线里执行 swag init 却提示 no Go files found，不是代码问题，是 swag 默认只扫当前目录下的 .go 文件，而 CI 常把源码放在子目录（如 src/）或用了多阶段构建，工作目录不对。

明确指定扫描路径：swag init -g main.go -o ./docs，其中 -g 指向主入口文件，-o 指定输出目录
确保 CI 步骤中执行 swag init 前，已经 go mod download 完成，否则依赖包里的类型（如 github.com/swaggo/http-swagger）可能无法解析
Swag v1.8+ 支持 --parseDependency 参数，但会显著拖慢生成速度，非必要不加；多数情况只需保证 -g 指向的文件 import 了所有要用到的模型类型
如果项目用了 Go Workspace（go.work），swag 不识别 workspace，必须 cd 进具体 module 目录再执行