Revel 框架不支持自动 Swagger 文档生成，因其路由基于反射且无参数/返回值解析与文档钩子；需用 swaggo 工具链：写规范注释→swag init 生成 docs/→在 init.go 中配置 revel.StaticDir["/swagger"] = revel.BasePath + "/docs"。
Revel 框架本身不带 Swagger 或 OpenAPI 文档生成功能，但可以通过 swaggo/swag 工具链实现自动化文档生成——关键在于「注释即文档」，且必须手动触发生成，不能热更新。
为什么不能直接用 Revel 内置机制生成文档
Revel 的路由是基于约定和反射自动注册的（比如 AppController.ShowUser 映射到 GET /users/{id}），但它不解析函数签名、不提取参数类型、也不收集返回结构。框架层没有预留文档元数据钩子，revel.App 或 revel.Controller 类型里找不到类似 GetDoc() 这样的接口。所以任何文档生成都得靠外部工具介入代码层。
怎么用 swaggo 为 Revel 添加 Swagger 文档
核心流程是：写符合 swaggo 规范的注释 → 用 swag init 扫描并生成 docs/ → 在 Revel 启动时挂载静态路由提供 /swagger/index.html。
- 确保项目根目录有
app/init.go（Revel 标准入口），它是swag init -g的必要目标文件 - 在控制器方法上方添加
// @Summary、// @Param、// @Success等注释，注意参数名要和函数签名一致（如func(c AppController) ShowUser(id int)对应// @Param id path int true "用户ID"） - 执行
swag init -g app/init.go -o docs，生成的docs/swagger.json必须存在，否则前端无法加载 - 在
app/init.go的init()函数里加一行：revel.InterceptFunc(func(c *revel.Controller) revel.Result { return nil }, revel.BEFORE, &revel.StaticFilter{})不够；实际要注册静态文件路由：revel.StaticDir["/swagger"] = revel.BasePath + "/docs"，然后访问/swagger/index.html
常见报错和绕过方式
运行 swag init 后提示 ParseComment error 或找不到 @Success，大概率是以下原因：
-
// @Success后面的结构体类型没加包路径，比如写{object} User而不是{object} models.User（Revel 默认把模型放在app/models，需显式写全） - 注释块和函数之间有空行，
swag会断开关联（必须紧贴函数上方，无空行） - 用了 Revel 的泛型写法（如
func(c AppController[T]) Do()），swaggo目前不支持泛型解析，会跳过整个函数 -
swag init找不到app/init.go中 import 的其他包（如models），需确认 GOPATH 或 Go Modules 开启，且所有依赖可正常go build
最易被忽略的一点：Revel 的 revel.Result 返回值不会被 swag 自动识别为响应体，你必须在注释里明确写出 // @Success 200 {object} models.User，不能指望它从 return c.RenderJSON(user) 推断结构。
