iris-swagger无法自动生成文档因需手动运行swag init生成docs/docs.go，且注释须写在导出handler上方、结构体字段须导出并含json tag，挂载时推荐用swaggo/gin-swagger.WrapHandler。
iris-swagger 无法自动生成接口文档？先确认是否用了正确插件
Go 的 Iris 框架本身不内置 Swagger 支持，必须借助第三方包。最常用的是 iris-contrib/swagger（基于 swaggo/swag），但注意：它不是运行时动态扫描路由生成文档，而是依赖 swag init 命令从 Go 注释中提取元数据生成 docs/docs.go。很多人卡在第一步——根本没装 swag CLI 或注释格式不对。
- 必须先全局安装
swag：运行go install github.com/swaggo/swag/cmd/swag@latest -
iris-contrib/swagger只是把生成好的docs/docs.go挂载为 HTTP 路由，不负责生成 - 所有
// @...注释必须写在 handler 函数上方（不是路由注册处），且函数需导出（首字母大写）
handler 上的 Swagger 注释怎么写才有效
Swagger 文档质量完全取决于注释的完整性和准确性。Iris 路由参数、请求体、响应结构都得靠注释显式声明，否则生成的文档里对应字段会缺失或为空。
-
// @Summary和// @Description是必填项，否则该接口不会出现在文档中 - 路径参数用
// @Param name path string true "描述"，其中name必须和ctx.Param("name")中的字符串一致 - JSON 请求体要标注结构体类型：
// @Param request body YourRequestStruct true "请求体"，且该结构体需有 JSON tag（如json:"field"） - 成功响应必须用
// @Success 200 {object} YourResponseStruct，否则 Swagger UI 显示 “No response defined”
示例 handler：
// @Summary 获取用户信息
// @Description 根据ID查询用户详情
// @Tags user
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} UserResponse
// @Router /users/{id} [get]
func GetUser(ctx iris.Context) {
id := ctx.Params().Get("id")
// ...
}
为什么访问 /swagger/index.html 报 404？检查 docs 包和路由挂载
常见错误是只生成了 docs/docs.go，但没在 Iris 应用中正确挂载。Iris 不像 Gin 那样提供开箱即用的 ginSwagger.WrapHandler()，需要手动调用 swagger.New() 并传入 docs.Doc。
- 确保已执行
swag init -g main.go（-g指定入口文件），生成的docs目录在项目根目录下 - 导入时路径必须是相对当前 main.go 的路径，比如
import "./docs"或import "your-module-name/docs"（模块名需匹配 go.mod） - 挂载代码必须放在
app := iris.New()之后、app.Listen()之前，且路由前缀建议用/swagger而非/docs（避免和静态资源冲突）
挂载示例：
import (
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger" // 注意：这里用的是 gin-swagger，不是 iris-contrib 的旧版
"./docs"
)
// 在 app 初始化后
app.Get("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
⚠️ 注意：iris-contrib/swagger 已归档，推荐直接用 swaggo/gin-swagger 的 WrapHandler —— 它兼容任何标准 http.Handler，Iris 的 iris.Context 底层就是 http.ResponseWriter + *http.Request，完全可用。
struct 字段没出现在请求/响应模型里？检查 struct 导出和 JSON tag
Swagger 解析结构体时只识别导出字段（首字母大写），且严格依赖 json: tag。即使字段名和 JSON key 一致，漏写 tag 也会导致字段被忽略。
- 非导出字段（小写开头）永远不出现，无论有没有 tag
-
json:"-"表示忽略；json:"field,omitempty"表示空值省略，但依然会出现在模型定义中 - 嵌套结构体字段也必须导出+有 tag，否则整个嵌套层级消失
- 数组类型写
[]User即可，不需要额外注释；map 类型目前支持有限，建议转为结构体
错误示例：name string `json:"name"` → 字段不导出，不会生成；正确应为：Name string `json:"name"`。
最容易被忽略的一点：每次修改 handler 注释或结构体后，必须重新运行 swag init，否则浏览器看到的还是旧文档。没有热更新，也没有自动监听 —— 这是 swaggo 的设计决定，不是 Iris 的限制。
