Revel 框架可通过 swaggo/swag 实现 Swagger 文档自动生成，关键在于正确编写注释、指定入口文件（如 swag init -g app/init.go）、导入 docs 包；需注意结构体路径、参数类型匹配、@Router 路径一致性及手动配置静态路由与 Swagger UI 资源。
Revel 框架本身不带 Swagger 支持，但能用 swaggo/swag 工具链实现文档自动生成——关键不是“能不能”，而是注释写对、生成路径指定准、docs 包被正确导入这三步漏一不可。
swag init 命令为什么总报错找不到入口文件？
Revel 项目没有标准的 main.go，swag init 默认会找它。你必须显式告诉 swag 哪个是启动入口：
- 确认你的 Revel 应用初始化文件（通常是
app/init.go或app/app.go）里有revel.Init调用和路由注册逻辑 - 运行命令时必须加
-g参数指定该文件：swag init -g app/init.go - 如果项目用了模块化结构（比如
controllers/单独目录），还要加-o docs明确输出目录，避免 swag 在错误路径下建docs - 常见错误信息：
ParseComment error in file xxx: cannot find type definition，说明注释里引用的结构体（如User）没被 swag 扫描到——确保结构体定义在可访问包内，且首字母大写
Revel 控制器函数注释怎么写才有效？
Revel 的控制器方法签名和 Gin/HTTP handler 不同（比如参数是 id int 而非 id string），注释里的 @Param 类型必须匹配实际类型，否则生成的 OpenAPI 文档参数类型会错：
-
@Param id path int true "用户ID"—— 这里int必须和ShowUser(id int)中的int一致；若写成string，Swagger UI 里输入框会显示为字符串，但后端实际接收整数，联调必失败 -
@Success 200 {object} models.User——models.User必须是完整包路径，比如github.com/yourname/yourapp/app/models.User，否则 swag 解析失败 - 不要省略
@Tags，它控制 Swagger UI 里的分组折叠，默认是 “default”，一堆接口挤在一起很难用 - Revel 的路由是通过
routes文件或revel.Intercept注册的，@Router注释里的路径必须和实际注册路径完全一致（包括前缀），例如@Router /api/v1/users/{id} [get]，不能漏掉/api/v1
生成的 docs 包怎么接入 Revel 路由？
Revel 没有 gin-swagger 那样的现成中间件，得手动注册静态路由并加载 docs 包：
- 先执行
swag init -g app/init.go，确认项目根目录下生成了docs文件夹，里面含swagger.json - 在
app/init.go的init()函数里 import：_ "your-project-root/docs"（注意是 underscore 引入，触发 docs 包的init()注册 swagger.json） - 在
app/routes文件末尾添加静态路由：GET /swagger/*filepath Static.Serve("swagger") - 把
docs/swagger.json和docs/swagger.yaml手动复制到public/swagger/目录下，并确保Static.Serve能读取该路径（Revel 默认只 servepublic/下内容） - 启动服务后访问
http://localhost:9000/swagger/index.html，而不是/docs或/swagger根路径
最容易被忽略的是：Revel 的 Static.Serve 不会自动识别 swagger.json 并挂载 UI，你必须自己提供 index.html（可从 github.com/swaggo/files 复制）并配好相对路径引用。否则页面加载空白，控制台报 404 —— 这不是 swag 问题，是静态资源路由没对齐。
