必须在proto的rpc方法上添加google.api.http注解并导入annotations.proto，否则Swagger为空；推荐使用protoc-gen-openapi生成OpenAPI 3.0规范，注意路径参数名与request字段严格一致、body映射准确、避免oneof用于对外API。

proto 文件里没加 google.api.http 注解，Swagger 就是空的

生成的 Swagger UI 里看不到任何接口，大概率是因为 proto 中只定义了 message 和 service，但没告诉工具“这个 RPC 方法对应哪个 HTTP 路径和方法”。protoc-gen-swagger 这类工具只认 google.api.http 扩展，不看 grpc-gateway 的 runtime 注册逻辑。

• 必须在 .proto 的 rpc 方法上显式加注解，比如：

  rpc GetUser(GetUserRequest) returns (GetUserResponse) {
    option (google.api.http) = {
      get: "/v1/users/{id}"
    };
  }

• 漏掉 import "google/api/annotations.proto"; 会导致编译失败，但有些 IDE 不报错，只静默跳过生成
• get/post 路径里的字段名（如 {id}）必须和 request message 中的字段名完全一致，大小写敏感

用 protoc-gen-openapi 还是 protoc-gen-swagger

两者都从 proto 生成 OpenAPI spec，但输出格式、兼容性和扩展能力差别不小。现在更推荐 protoc-gen-openapi，它原生支持 OpenAPI 3.0，而老版 protoc-gen-swagger 只到 2.0，Swagger UI v5+ 对 2.0 支持越来越弱。

• protoc-gen-openapi 默认生成 openapi.yaml，可直接被 Swagger UI 或 Redoc 加载；protoc-gen-swagger 输出的是 swagger.json，需额外配置才能适配新版 UI
• 如果用了 google.api.field_behavior（比如 REQUIRED），protoc-gen-openapi 能转成 OpenAPI 的 required 字段，老工具基本忽略
• 命令行参数不同：--openapi-out=. vs --swagger_out=logtostderr=true:.，拼错就静默失败

生成的文档里 path 参数或 body 类型不对

常见现象是 Swagger 显示某个字段是 string，但实际 gRPC 接口要求的是 int64；或者 body 里该出现的字段没出现——这通常不是工具 bug，而是 proto 定义和 HTTP 映射没对齐。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

• HTTP path/query 中提取的字段（如 {user_id}）必须在 request message 中声明为 scalar 类型（int64, string 等），不能是嵌套 message
• request message 中未出现在 path 或 query 里的字段，默认进 body；但如果用了 body: "*"，整个 message 当 body；用 body: "field_name" 则只取指定字段，其余丢弃 —— 文档会如实反映这个行为
• gRPC 的 oneof 在 OpenAPI 里没有直接等价物，protoc-gen-openapi 会生成 anyOf，但部分 Swagger UI 版本渲染异常，建议避免在对外 API 的 request 中用 oneof

Swagger UI 页面加载后报 Failed to fetch 或 404

生成的 openapi.yaml 没问题，但 UI 打开后调用不到后端，多数是路径或 CORS 配置脱节，而不是文档生成环节的问题。

立即学习“go语言免费学习笔记（深入）”；

• 检查 Swagger UI 加载时请求的 /v1/swagger/openapi.yaml 是否真能返回内容（curl 一下），很多项目把文件放在 static/ 下但没配 Web 服务路由
• UI 发起的 API 请求地址默认是相对路径，比如当前页是 http://localhost:8080/swagger/，它就会往 http://localhost:8080/v1/users/123 发请求 —— 如果你的 gRPC-Gateway 服务跑在另一个端口（如 8090），需要在 UI 初始化时设 urls.primaryName 或改 requestUrl
• 浏览器控制台若报 CORS 错误，不是文档问题，是 gateway 服务没开 Access-Control-Allow-Origin，Gin/Chi 等框架需显式加 middleware

实际跑通的关键不在工具链多炫，而在 proto 注解、HTTP 映射、静态资源路由、网关服务这四层之间严丝合缝。少一层对齐，Swagger 就只是个好看的空壳。