Iris v12集成Swagger必须严格匹配版本:使用iris-contrib/swagger/v12、swag@v1.10.5,注解置于handler上方且含@Summary/@Description,每次修改后执行swag init -g main.go,路由注册须在中间件前,/swagger/doc.json可访问是关键验证点。

Iris v12 项目必须用 iris-contrib/swagger/v12,配 swag@v1.10.5,否则 /swagger/index.html 白屏或 404。
版本匹配是第一道坎
go get 默认拉取最新版,但 Iris v12 和 swagger 不兼容最新分支。常见错误包括:
-
go get github.com/iris-contrib/swagger→ 拉到 v13 或无版本后缀的 master 分支,运行时 panic:cannot find package "github.com/iris-contrib/swagger/v12/swaggerFiles" -
swag init生成的docs/docs.go里 import 路径含v2(来自 swag v1.16+),而iris-contrib/swagger/v12只认v12路径
正确做法只有三步:
go env -w GOPROXY=https://goproxy.cn,directgo get github.com/swaggo/swag/cmd/swag@v1.10.5go get github.com/iris-contrib/swagger/v12@v12.2.0-alpha
注解写在哪、怎么写才生效
Swagger 注解必须紧贴 handler 函数上方(不能写在 struct 方法内部,也不能塞进 controller 的 BeforeActivation 里)。Iris 不扫描目录,每个接口都得手动覆盖。
关键约束:
-
@Summary和@Description缺一不可,否则该接口不会出现在文档中 -
@Accept和@Produce值必须是application/json,写成json会失效 -
@Router的路径必须和实际注册路由完全一致(比如注册的是app.Get("/user/list", getUserList),注释就得写@Router /user/list [get])
示例(正确):
// @Summary 获取用户列表
// @Description 返回全部用户信息
// @Tags 用户
// @Accept application/json
// @Produce application/json
// @Success 200 {array} models.User
// @Router /user/list [get]
func getUserList(ctx iris.Context) {
ctx.JSON([]models.User{{Name: "a", Age: 20}})
}
每次改完注释都要重新生成 docs
swag init 不是“一次配置永久生效”的命令。只要改了任何 @xxx 注释,就必须重新执行:
- 若入口文件是
main.go,运行:swag init -g main.go - 若入口在
cmd/app/main.go,就得写全路径:swag init -g cmd/app/main.go - 生成的
docs目录需被_ "./docs"显式导入,否则doc.json加载失败
没重跑 swag init,前端看到的就是旧文档 —— 这是最常被忽略的操作点。
路由注册顺序决定能否访问 Swagger UI
Swagger 中间件必须在所有业务路由注册前挂载,且路径要覆盖完整:
- 错误写法:
app.Use(swagger.CustomWrapHandler(...))→ 中间件模式不适用,会拦截所有请求 - 正确写法:
app.Get("/swagger/{any:path}", swagger.CustomWrapHandler(config, swaggerFiles.Handler)) -
config.URL必须指向可访问的/swagger/doc.json,例如:"http://localhost:8080/swagger/doc.json" - 验证是否成功:直接访问
http://localhost:8080/swagger/doc.json,能返回 JSON 就说明后端就绪
文档能生成、中间件也挂了,但 /swagger/doc.json 返回 404,大概率是路由注册顺序错了,或者 _ "./docs" 没导入。


















