因iris mvc路由在运行时通过b.handle动态注册，而swag是静态分析工具，无法识别mvc.result方法及beforeactivation中的路由绑定，导致接口漏生成。
为什么MVC结构下直接用swag init会漏掉接口？
因为Iris的MVC控制器（如UserController）是通过mvc.Application.Register注册的，不是普通函数调用；swag工具默认只扫描顶层函数和HTTP handler，对mvc.Result返回值、BeforeActivation注册的路由不感知，导致生成的docs/swagger.json里空空如也。
常见错误现象：swag init后访问/swagger/index.html能看到UI，但所有接口列表为空，控制台也没报错。
根本原因：Iris MVC的路由绑定发生在运行时（b.Handle），而swag是静态代码分析工具，无法解析这种动态注册逻辑。
- 必须把接口定义“显式写回源码”——即在控制器方法上加完整Swagger注解，哪怕它只是个
mvc.Result方法 - 注解要放在
func声明上方，不能放在BeforeActivation里或结构体字段上 -
@Router路径必须与b.Handle注册的实际路径完全一致（包括前缀），比如b.Handle("GET", "/user/getAll", "GetAllUsers")对应@Router /user/getAll [get]
怎么给MVC控制器方法加有效的Swagger注解？
注解位置和字段必须严格匹配Iris MVC的执行链。重点不是“有没有注解”，而是“注解是否被swag识别并映射到正确路由”。
以GetAllUsers为例：
// @Summary 获取用户信息
// @Description 获取所有用户信息
// @Tags 用户
// @Accept json
// @Produce json
// @Success 200 {array} model.User "用户列表"
// @Failure 400 {object} mvc.Response "请求参数错误"
// @Router /user/getAll [get]
func (u *UserController) GetAllUsers() mvc.Result {
// 实际逻辑
users := []model.User{{Name: "zhangsan", Age: 20}}
return mvc.Response{
ContentType: "application/json",
Code: 200,
Content: marshalJSON(users),
}
}
-
@Router里的路径必须和b.Handle第二个参数（即pattern）完全一致，大小写、斜杠都不能错 -
@Success/@Failure中的类型要写Go原始类型或已定义结构体全名，如model.User，不能写*model.User或匿名struct - 如果方法有
@Param，需确认它是否真被Iris绑定——比如query参数要靠ctx.URLParam或ctx.FormValue手动取，swag不会自动推导
生成文档时swag init命令该加什么参数？
默认swag init只扫当前目录，而Iris MVC的控制器、模型、路由注册往往分散在controller/、model/、main.go等不同包。不指定范围，swag就找不到结构体定义，导致响应模型显示为object而非具体字段。
必须显式指定入口和扫描路径：
- 用
-g main.go指向应用启动文件（确保它import了所有控制器包） - 用
-o ./docs指定输出目录，避免覆盖已有docs/ - 加
--parseDependency让swag递归解析依赖包里的结构体（否则model.User会被当黑盒） - 如果模型在
./model目录，额外加--parseVendor（尽管不推荐vendor，但有些项目用了）
典型命令：swag init -g main.go -o ./docs --parseDependency
为什么Swagger UI能打开，但点接口报404？
这是路由配置和文档服务路径没对齐的典型表现。Iris本身不托管/swagger/*any下的静态资源，全靠swaggerFiles.Handler提供HTML/JS/CSS，而swagger.json的URL由Config.URL决定——两者必须指向同一份文档数据。
常见错误：
- 文档生成在
./docs/swagger.json，但Config.URL写成"http://localhost:8080/swagger/doc.json"（少了个s） - 用
swagger.WrapHandler但没配Config，它默认读/swagger.json，而你生成的是/docs/swagger.json - 反向代理环境下，前端请求
/swagger/v1/swagger.json被nginx转发错路径
正确做法（以生成到./docs为例）：
config := swagger.Config{
URL: "http://localhost:8080/docs/swagger.json", // 必须和实际HTTP可访问路径一致
}
app.Get("/swagger/*any", swagger.CustomWrapHandler(&config, swaggerFiles.Handler))
然后确保http://localhost:8080/docs/swagger.json能直接curl通——这是整个链路最脆弱的一环，也是最容易被忽略的调试起点。
