能接入Swagger但需手动补全三块拼图:swag CLI扫描注释生成docs/、gin-swagger中间件加载UI、_ "your-module-name/docs"触发文档注册;缺一则/swagger/index.html 404或空白。

能接入,但必须手动补全三块拼图:swag CLI 扫描注释生成 docs/、gin-swagger 中间件加载 UI、_ "your-module-name/docs" 触发文档注册——缺一不可,否则 /swagger/index.html 要么 404,要么空白。
swag init 为什么没生成 docs/ 目录?
根本原因不是命令没跑,而是注释没被识别。常见断点:
-
swag init默认只扫描当前目录及子目录下的.go文件,如果 handler 分散在handlers/或api/下,得加-d ./显式指定根目录 - 全局注释(
@title、@version)必须写在main.go顶部(package后、import前),且不能跨文件;少一个@title或换行错位,swag init就静默跳过 - 结构体字段用了
swaggerignore:"true"却没加json:tag,或类型名写成User而非models.User(包名不全),会导致swagger.json里对应字段为空或缺失 - Go Modules 启用后,
swag init必须在go.mod所在根目录执行,否则解析路径错乱,docs/docs.go里变量名可能带错包前缀
浏览器打开 /swagger/index.html 是空白页
90% 是 docs 包没正确导入或路径错。关键检查点:
- 确认
main.go的import块里有这一行:_ "your-module-name/docs"—— 这里的your-module-name必须和go.mod第一行完全一致,不能是./docs或docs -
gin-swagger注册路由时,必须用ginSwagger.WrapHandler(swaggerFiles.Handler),不能写成router.Static("/swagger", "./docs"),后者只暴露 JSON 文件,不加载 UI - 确保
github.com/swaggo/files版本与gin-swagger兼配,例如gin-swagger@v1.5.1对应files@v0.3.3;版本错位会导致swaggerFiles.Handler编译失败 - 启动服务后,先访问
/swagger/swagger.json看是否返回有效 JSON;如果 404,说明docs包没注册;如果返回空对象{},说明swag init没扫到注释
@Param 和 @Success 怎么写才不报错?
参数位置、类型、结构体引用这三点最容易写反:
立即学习“go语言免费学习笔记(深入)”;
-
@Param id path int true "用户ID":表示路径参数,URL 是/users/{id},不是/users?id=1 -
@Param username query string true "用户名":表示查询参数,URL 是/users?username=xxx -
@Param user body models.UserCreateRequest true "用户数据":body必须接已定义结构体,且包名要写全;models.UserCreateRequest如果实际在internal/models下,就得写成internal/models.UserCreateRequest -
@Success 201 {object} models.UserResponse:响应结构体也必须可导出(首字母大写),且字段有json:tag,否则生成的 schema 里字段为空 - 所有
@开头的注释必须在同一注释块内,不能拆成多段//行,中间不能有空行
最常被忽略的是 _ "your-module-name/docs" 这行导入——它不参与任何逻辑,只触发 docs/docs.go 里的 init() 函数把文档数据挂进内存。没这行,WrapHandler 拿不到任何内容,页面自然空白。别信“反正能编译就对了”,这行不起眼,但卡死整个链路。


















