应选swag CLI,因go-swagger已停止维护、泛型支持差且仅支持OpenAPI 2.0;swag活跃轻量、原生支持OpenAPI 3.0,需用go install github.com/swaggo/swag/cmd/swag@latest安装,并在项目根目录执行swag init -d指定路径、-g指定入口、-o指定输出。

用 swag CLI 生成 swagger.json,别碰 go-swagger
现在 Go 生态里唯一能稳定跑起来的方案是 swag,不是 go-swagger。后者已停止维护,对泛型支持差,扫描 struct 时经常漏字段、嵌套错乱,且只支持 OpenAPI 2.0;而 swag 活跃更新、轻量、原生支持 OpenAPI 3.0,跟 gin、echo、net/http 都能直接对接。
安装命令必须用新路径:
go install github.com/swaggo/swag/cmd/swag@latest
旧路径 github.com/swaggo/swag 已失效,装了也运行不了。
- 必须在项目根目录(含
go.mod和入口文件)执行swag init,否则扫描不到跨包的 handler - 如果路由分散在
internal/handler、pkg/api等位置,得显式加-d:swag init -d internal/handler -d pkg/api -g cmd/main.go -o docs/ -
swag init不进vendor、不进外部 module,所有@Success引用的 struct 必须定义在本项目内,或用// @Model显式声明别名
handler 函数上方的注释必须紧贴、三要素齐全
swag 只认紧贴 handler 函数正上方的 // @xxx 注释块,中间插一行空行或其它注释,整个接口就从文档里消失。
立即学习“go语言免费学习笔记(深入)”;
最简可用组合只有三个:
-
// @Summary—— 接口标题,没它 Swagger UI 里显示为u -
// @Router—— 路径和方法,例如// @Router /api/v1/users [get],末尾别加/,否则前端调用 404 -
// @Success 200 {object} models.UserResponse—— 返回类型必须是导出 struct(首字母大写),且字段带json:tag,否则 schema 里全是空对象
常见错误写法:
// @Success 200 {array} []User ❌ swag 不支持 []User 缩写<br>// @Param id path uuid.UUID true "ID" ❌ uuid.UUID 不被识别,得写 string 并靠业务校验<br>// @Param user body User true "用户" ❌ User 必须是顶层导出 struct,不能是匿名或函数内定义
结构体字段必须导出 + 带 json tag,否则字段不进 schema
swag 扫描 struct 时完全依赖 Go 的导出规则和 json: tag。小写字母开头的字段、没 tag 的字段、或者 tag 是 json:"-" 的,一律不会出现在生成的 swagger.json 的 components.schemas 里。
- 字段名大小写决定 JSON key 名(除非你用
-p camelcase参数强制转换) -
omitempty不影响字段是否出现,只影响默认值逻辑 - 嵌套 struct 自动展开,但
map[string]interface{}或interface{}会变成object{},没法描述结构 - 数组参数要写全:
// @Param ids query array true "ID列表" collectionFormat:multi items.type:string,不能简写成type: []string
集成 Swagger UI 时 docs/docs.go 必须被 main 包导入
生成的 docs/docs.go 是个 Go 包,不是静态资源。如果不被 main 包 import,编译时会被丢弃,httpSwagger 加载不到任何内容,UI 里只有首页、没有 API 列表。
示例(以 gin 为例):
import (<br> _ "your-project-path/docs" // 注意是下划线导入,触发 init()<br> "github.com/swaggo/gin-swagger"<br> "github.com/swaggo/files"<br>)<br><br>func main() {<br> r := gin.Default()<br> r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))<br> // ...<br>}
中文乱码?检查三件事:
- 所有
.go文件保存为 UTF-8 编码(file -i handler.go确认) -
docs/docs.go生成后手动打开,确认中文没变成\u4f60\u597d—— 如果变了,说明源文件编码不对或注释写在了非 UTF-8 环境下 - 浏览器访问
/swagger/index.html时,页面右键「查看页面编码」是否为 UTF-8
最常被忽略的是:handler 函数所在文件的 package 声明必须合法,且不能是 package main(除非它真注册了路由),否则 swag 直接跳过整个文件。


















