必须在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 映射没对齐。
- 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
