Revel框架本身不支持Swagger，但可通过swaggo/swag集成：需正确编写注释、指定-swag init -g app/init.go入口、确保docs包被导入并手动注册路由服务静态资源。
Revel 框架本身不带 Swagger 支持，但能用 swaggo/swag 工具链完成集成——关键不是“能不能”，而是注释写得对不对、swag init 扫描路径配得准不准、生成的 docs 包有没有被正确引入。
为什么 swag init 总是报错“cannot find package”
这是最常卡住的第一步。Revel 项目结构和标准 Go module 不完全一致，swag 默认按 main.go 入口找包，而 Revel 的启动入口在 app/init.go 或 app/app.go（取决于版本）。如果没指定入口，swag 就会找不到控制器所在的包路径。
- 必须显式指定入口文件：
swag init -g app/init.go（不是main.go，也不是app/app.go，要看你项目里实际调用revel.Run()的位置） - 确保
app/init.go上方有正确的package app声明，且该文件能 import 到所有控制器所在的包（比如controllers） - 如果控制器分散在多个子包（如
controllers/v1），需确认这些包被app/init.go或其依赖链间接 import，否则swag扫不到 - Go modules 开启状态下，
swag要求当前目录是 module 根，且go.mod中包含require了所有用到的包（包括github.com/revel/revel）
@Param 和 @Success 注释怎么写才不会丢字段
Revel 的参数绑定机制和 Gin/Spring Boot 不同：它直接从 URL path、query、body 自动注入到函数参数，但 swag 不懂 Revel 的绑定逻辑，只认注释。写错注释会导致文档里参数缺失、类型错误或响应结构为空。
-
@Param id path int true "用户ID"中的path必须和路由定义一致（如/users/{id}），不能写成query或漏掉{} - 如果参数来自
revel.Params或revel.Binder绑定的 struct（比如type UserReq struct { Name string `json:"name"` }），必须用@Param user body UserReq true "用户信息"，且确保UserReq类型在当前作用域可导出（首字母大写）、有 JSON tag -
@Success 200 {object} User中的User必须是完整可导入路径，如@Success 200 {object} models.User；如果类型在controllers包内定义，又没被其他包引用，swag可能无法解析其字段 - 避免用匿名 struct 做返回值，
swag解析不了：return c.RenderJSON(map[string]string{"ok": "true"})→ 文档里只会显示object，没字段
生成的 docs 怎么接入 Revel 路由
swag init 生成的 docs 是静态资源，Revel 不像 Gin 那样有现成的 gin-swagger 中间件，得手动注册一个 handler 来服务 swagger.json 和前端页面。
- 先在
app/init.go的init()函数里 import 生成的docs包：_ "your-project-name/docs"（注意路径要和go mod名一致） - 在
app/routes文件中加一条静态路由：GET /swagger/*filepath Static.Serve("swagger") - 把
docs/swagger.json复制到public/swagger/目录下，并在public/swagger/index.html中修改url指向/swagger/swagger.json - 更稳妥的做法是写一个自定义 controller，用
c.RenderText()返回docs.SwaggerJSON，再配个前端页面加载它（避免文件路径权限或缓存问题）
最容易被忽略的是：Revel 的 revel.Intercept 或中间件可能拦截 /swagger/* 路径，导致 404；还有就是 docs 包没被 import 导致 swagger.json 内容为空——这两个问题不查日志根本看不出来。
