Revel 可通过 swaggo/swag 实现 Swagger 文档自动生成，关键在于正确配置注释、swag init 成功生成 docs/、手动注册 docs 包并暴露路由；需确保入口文件含 main() 或 revel.Init()、全局注释统一置于 init.go、参数类型与控制器签名严格一致。
Revel 框架本身不带 Swagger 支持，但能用 swaggo/swag 工具链实现文档自动生成——关键不在框架是否“内置”，而在你能否让注释被正确扫描、swag init 成功输出 docs/、且路由能加载静态资源。
swag CLI 安装与初始化必须成功
很多项目卡在第一步：命令执行后没报错，但 docs/ 目录压根没生成。这不是 Revel 的锅，而是 swag 找不到入口函数或注释格式不对。
-
swag必须安装到$GOPATH/bin且该路径已加入$PATH，否则swag init -g app/init.go会静默失败 -
-g参数指定的入口文件（如app/init.go）必须包含func main()或revel.Init()调用，否则扫描器无法建立包依赖图 - 若项目用了 Go Modules，确保
go.mod中 module 名与实际导入路径一致，否则swag会跳过所有控制器包
@APIVersion 和 @Title 注释必须写在同一个文件里
全局元信息注释（@title、@version、@description 等）如果分散在多个文件，swag init 只取第一个遇到的完整块，其余全丢弃——结果就是生成的 docs/swagger.json 里 info 字段为空，Swagger UI 加载失败或显示“undefined”。
- 推荐统一写在
app/init.go顶部，紧贴package app声明之后、import之前 - 必须包含
@title和@version，缺一不可；@BasePath建议显式设为/api或对应前缀，避免路径错位 - 不要混用旧版
@APIVersion（yvasiyarov/swagger 风格）和新版@version（swaggo/swag 风格），后者才是当前主流工具链识别的
控制器函数注释要匹配 Revel 的参数绑定方式
Revel 使用路径参数自动绑定（如 func(c AppController) ShowUser(id int)），但 @Param id path int 注释里的 path 类型必须与实际路由定义一致，否则参数在 UI 中不显示或类型错误。
- 路径参数用
@Param name path type，例如// @Param id path int true "用户ID" - 查询参数用
@Param name query type，如// @Param page query int false "页码" - 请求体必须标注
@Param name body TypeName，且TypeName是结构体名（如UserCreateRequest），不能是*UserCreateRequest或别名 - 返回结构用
@Success 200 {object} User，注意{object}是固定字面量，不是 Go 类型语法
docs 包注册和路由暴露容易漏掉
生成 docs/ 目录只是第一步。Revel 没有类似 Gin 的 gin-swagger 中间件，得手动把 docs 包挂到路由上，否则访问 /swagger/index.html 就是 404。
- 先执行
go get -u github.com/swaggo/files（注意版本号，@v0.3.3是当前兼容 Revel 的稳定版） - 在
app/init.go的init()函数中 import_ "your-project-name/docs"（下划线导入触发 docs 包 init） - 在
routes文件中加一行：GET /swagger/*filepath revel.Static.Serve("public/swagger")，并确保public/swagger是软链或复制了docs下的全部内容 - 或者更稳妥：用 Revel 的
Static.Serve直接指向docs目录绝对路径，避免相对路径解析问题
最容易被忽略的是注释与代码结构的耦合性：Revel 控制器方法签名变了（比如从 id int 改成 id string），但忘了同步改 @Param 注释里的 type，结果文档里参数类型还是 int，前端按整数传字符串就 400 —— 这类不一致不会报错，但会在线上联调时才暴露。
