swag init 无法生成 docs 目录的根本原因是 Revel 启动入口不在 main.go 而在 app/init.go，且 swag 默认不扫描该文件；必须显式执行 swag init -g app/init.go 并将全局注释置于其顶部。
Revel项目里swag init 为什么生成不了 docs 目录
根本原因是 Revel 没有像 Gin 那样默认把 main.go 或 app/init.go 当作入口扫描点，swag init 默认只找 main.go 里的注释；而 Revel 的启动逻辑在 app/init.go，且控制器分散在 app/controllers/ 下。不指定入口文件，swag 就找不到任何 @ 注释。
必须显式告诉它从哪开始扫描：
- 执行
swag init -g app/init.go，确保@title、@version等全局注释就写在这份文件顶部（package 声明之后、import 之前） - 控制器函数上方的接口级注释（如
@Summary、@Router）必须紧贴函数声明，不能隔空行，也不能写在结构体方法里（Revel 控制器是值类型方法，func (c AppController) ShowUser(...)才有效） - 若用
revel.NewApp()方式启动，确认app/init.go是唯一被swag识别的初始化入口，其他app/conf/routes.conf里的路由定义不会被解析
Revel 控制器上加的 Swagger 注释不生效
Revel 的注释解析比 Gin 更严格：它不支持 // @Param xxx body ... 这种 Gin 风格的请求体描述，因为 Revel 默认用表单或 URL 查询参数传参，没有原生 JSON body 绑定机制。直接照搬 Gin 的注释会导致字段丢失或文档空白。
正确写法要匹配 Revel 实际接收方式：
-
@Param id path int true "用户ID"—— 对应func (c AppController) ShowUser(id int) revel.Result中的路径参数 -
@Param name query string false "用户名模糊查询"—— 对应c.Params.Get("name")这类 query 参数 - 避免使用
@Accept json和@Param xxx body ...，除非你手动解析了c.Request.Body并做了 JSON 反序列化，否则 Swagger UI 会显示参数但后端根本收不到 -
@Router /users/{id} [get]中的路径必须和routes.conf里定义的完全一致（包括大小写、斜杠结尾），否则 UI 上点击 “Try it out” 会发错地址
浏览器访问 /swagger/index.html 返回 404 或空白页
Revel 没有内置 gin-swagger 这类中间件，不能靠一行代码注册路由。docs 目录生成后，必须手动把静态文件挂载到 Revel 的 HTTP 路由系统中。
常见错误是只生成了 docs/swagger.json 却没暴露给前端：
- 在
app/init.go的init()函数里，添加静态路由：revel.InterceptFunc(static.Serve, revel.BEFORE)不够，得明确指向docs目录 - 更稳妥的做法：在
app/controllers/swagger.go新建一个控制器，用revel.RenderFile("docs/swagger.json")返回 JSON，并在routes.conf中加一行：GET /swagger/doc.json Swagger.Docs - UI 页面需额外托管——把
github.com/swaggo/files的内容复制进public/swagger/，再通过GET /swagger/*filepath Application.ServeStatic暴露出去；否则/swagger/index.html本身就没文件可返回
Revel + Swagger 文档能交互但参数总是 400 错误
这几乎全是参数绑定逻辑不匹配导致的。Revel 的参数提取依赖 c.Params（来自路由和 query）和 c.Params.Get("key")，而 Swagger UI 发送的请求默认带 Content-Type: application/json，但 Revel 不会自动解析 JSON body 到控制器参数。
想让 “Try it out” 真正可用，必须做两件事：
- 在控制器里手动读取并解析 JSON：
var req UserCreateRequest; err := json.NewDecoder(c.Request.Body).Decode(&req)，然后注释改用@Param user body models.UserCreateRequest true "用户数据" - 或者，放弃 JSON body，改用表单提交：在 Swagger 注释中删掉
@Accept json，加上@Consumes application/x-www-form-urlencoded，并在 UI 的 “Try it out” 区域切换到 “form-data” 模式 - 别忽略 Revel 的
Validation机制——如果控制器里调用了c.Validation，而 Swagger 提交的字段名和结构体 tag（如json:"user_name"）不一致，验证失败也会返回 400，但错误信息不会透出到 UI
Revel 的 Swagger 集成不是“装完就能用”，它要求你对框架参数绑定机制有真实理解。最常被忽略的一点是：Swagger UI 发什么，Revel 就收什么；但 Revel 默认不收 JSON body，你得亲手接住它，否则所有交互都只是假动作。
