Iris框架怎么使用Swagger生成API接口说明-Golang-PHP中文网

Iris v12必须严格匹配iris-contrib/swagger/v12及swag v1.10.5，注解需置于handler上方且含@Summary/@Description，每次修改后执行swag init -g main.go，/swagger/doc.json可访问是关键验证点。

iris框架怎么使用swagger生成api接口说明

必须严格匹配 Iris 主版本与 iris-contrib/swagger 分支，否则 /swagger/index.html 白屏或 404，不是配置问题，是 Go module 路径解析失败。

确认 Iris 和 swagger 版本是否兼容

Iris v12.x（如 12.2.5）只能用 github.com/iris-contrib/swagger/v12，不能用无后缀的 github.com/iris-contrib/swagger 或 v13。常见错误是执行 go get github.com/iris-contrib/swagger，结果拉取了不兼容的最新版。

swag CLI 工具必须锁定为 v1.10.5：执行 go get github.com/swaggo/swag/cmd/swag@v1.10.5
iris-contrib/swagger 必须显式指定 @v12.2.0-alpha 或对应 v12 的 tag，例如 go get github.com/iris-contrib/swagger/v12@v12.2.0-alpha
检查生成的 docs/docs.go：若其中 import 含 v2 或 v13，说明 swag init 用了错版，需清理 docs/ 目录后重试

注解写法和 `swag init` 执行时机

Swagger 注解必须写在 handler 函数上方（不是 struct 方法内部），且 @Summary 和 @Description 缺一不可，否则该接口不会出现在文档中。

Iris框架 12.2.5

Iris框架 12.2.5 版本源码包下载，适合需要 MVC Singleton 控制器、依赖注入字段控制和 debug 错误日志改进的开发者。

下载

@Accept 和 @Produce 值必须是 application/json，写成 json 会导致解析失败
@Router 的路径要和实际注册路由完全一致（包括前缀、大小写、斜杠结尾）
每次修改注释后，必须重新运行 swag init -g main.go；若入口文件是 cmd/app/main.go，就得写全路径 swag init -g cmd/app/main.go
Iris 不支持自动扫描 controller 目录，所有 handler 都得手动加注解

路由注册顺序和中间件冲突

swagger.WrapHandler 必须注册在任何自定义中间件之前，否则可能被拦截或路径匹配失败。

正确写法：app.Get("/swagger/*any", swagger.WrapHandler(swaggerFiles.Handler)) 放在 app.Use(...) 或 app.Party(...).Use(...) 之前
如果用了 Party 分组（如 api := app.Party("/api")），不要把 Swagger 路由注册到分组下，必须挂到根 app
验证是否生效：启动服务后直接访问 /swagger/doc.json，能返回 JSON 即说明后端文档已就绪；/swagger/index.html 白屏大概率是前端加载 doc.json 失败（路径不对或 CORS）

最容易被忽略的是 swag init 生成的 docs/docs.go 中 import 路径与你 go get 的 iris-contrib/swagger/v12 实际路径不一致——Go 模块系统不会自动做版本映射，必须人工对齐。只要报 cannot find package "github.com/iris-contrib/swagger/v12/swaggerFiles"，第一反应不是改代码，而是检查 go.mod 里 iris-contrib/swagger 的版本声明和 docs.go 里的 import 是否完全一致。