搭建Golang环境并配置自动生成API文档工具-Golang-PHP中文网

swag init 报错或 swagger ui 无接口的根本原因是工具链未对齐、扫描路径未指定或注释格式不合规；必须用 go install 安装并确保 $path 包含 $gobin，显式指定 -d 和 -g 参数，注释需紧贴函数且无空行，结构体字段须导出并带 json tag。

搭建golang环境并配置自动生成api文档工具

Go 环境装好但 swag init 报 command not found，或者生成了 docs/docs.go 却在 Swagger UI 里看不到接口——问题几乎都出在工具链没对齐、扫描路径没指定、或注释格式被忽略。不是代码写得不对，是 swag 的解析规则和你预期的不一致。

根本原因不是没下载，而是二进制没进 $PATH，或用了已失效的安装路径。

go install github.com/swaggo/swag/cmd/swag@latest 是 Go 1.21+ 唯一推荐方式；go get 已废弃，且 github.com/go-swagger/go-swagger/cmd/swagger 地址在 2026 年已彻底不可用
装完必须验证：swag --version 能输出版本号才算成功；如果报 command not found，请检查 $GOPATH/bin（或 $GOBIN）是否在 shell 的 $PATH 中
macOS/Linux 用户常漏掉 source ~/.zshrc；Windows 用户需重启 PowerShell 才能读取新环境变量

swag 不会跨目录猜路由逻辑，它只扫你明确告诉它的 .go 文件，且要求这些文件里有合法的 package 声明和无语法错误。

Golang Samber Do

使用 samber/do 在 Golang 中实现依赖注入 — 服务容器、生命周期管理、作用域、健康检查、优雅关闭和模块组织

下载

默认只扫当前目录及子目录；若路由分散在 internal/handler 和 pkg/api，必须显式加 -d 参数：swag init -d internal/handler -d pkg/api
入口文件（如 cmd/app/main.go）要用 -g 指定：swag init -g cmd/app/main.go，否则可能漏掉 router := gin.New() 之后的注册逻辑
handler 文件不能是 package main（除非它真写了 r.GET()），建议统一用 package handler 或 package api
任何 .go 文件只要含语法错误（比如少个括号、导包没用），整份文件会被跳过，不报错也不提示

不是 Gin 路由没注册，而是静态资源没挂对路径，或 docs/docs.go 没被 import。

必须确保 swag init 成功后，项目根目录下存在 docs/docs.go 和 docs/swagger.json
docs/docs.go 必须被 import：在 main.go 顶部加一行 import _ "./docs"（注意路径是相对路径，且带下划线）
Gin 挂载必须用 ginSwagger.WrapHandler，不能用 router.Static()：r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))——*any 不能省，否则 /swagger/swagger-ui.css 这类子资源全 404
挂载语句必须在 gin.Default() 之后、r.Run() 之前；顺序反了，中间件不会生效

swag 不反射结构体，也不读函数签名，它只认紧贴函数上方、格式严丝合缝的注释块。

// @Summary 必须在函数正上方，且**前后都不能有空行**；写成 /* @Summary ... */ 或缩进的 // @Summary 都无效
// @Success 200 {object} model.UserResponse 中的 model.UserResponse 必须是已导出 struct（首字母大写），且每个字段必须有 json: tag；type User struct { Name string } 会丢失 Name 字段，必须写 Name string `json:"name"`
时间字段别依赖默认行为：CreatedAt time.Time `json:"created_at" time_format:"2006-01-02T15:04:05Z"`，否则文档里可能变成数字时间戳
body 类型参数必须用 // @Param user body model.User true "用户信息"，其中 model.User 要有 // @Model 注释，且不能是 *User 或 map[string]interface{}