grpc-gateway 怎么在 OpenAPI 响应的 schema 中引用任意消息【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway当你用 grpc-gateway 的protoc-gen-openapiv2插件生成 OpenAPISwagger文档时每个 RPC 的响应 schema 默认取自该 RPC 的返回类型。如果你的接口需要返回一个与返回类型不同的统一结构——比如一个错误消息、一个枚举、或者其他文件里定义的消息——就需要在响应描述里通过ref引用任意消息。本文基于仓库文档 Using arbitrary messages in response description 说明具体做法在 proto 选项里给响应加一个schema.json_schema.ref生成后 OpenAPI 文档中该响应的 schema 就会变成指向目标消息定义的$ref。前提条件你的 proto 文件要使用protoc-gen-openapiv2的自定义注解即已经import protoc-gen-openapiv2/options/annotations.proto;该导入同时提供openapiv2_swagger、openapiv2_operation等选项定义见 annotations.proto。已具备生成环境。按 README 的说明使用buf时把buf.build/grpc-ecosystem/grpc-gateway加入buf.yaml的deps使用protoc时需要把本仓库protoc-gen-openapiv2/options目录下的 protobuf 文件拷贝到你自己的 proto 目录树中并让protoc能在-I路径里找到它们。在文件级响应中通过 ref 引用消息以一个结构为例取自文档示例syntax proto3; package example.service.v1; import protoc-gen-openapiv2/options/annotations.proto; service GenericService { rpc GenericRPC(GenericRPCRequest) returns (GenericRPCResponse); } message GenericRPCRequest { string id 1; } message GenericRPCResponse { string result 1; }如果想让该 proto 文件里所有 RPC的 OpenAPI 响应都包含一个自定义响应例如 400在文件上追加openapiv2_swagger选项并定义好被引用的消息option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) { responses: { key: 400 value: { description: Returned when the request is malformed. schema: { json_schema: {ref: .example.service.v1.GenericResponse} // Must match the fully qualified name of the message } } } }; message GenericResponse { repeated string resources 1; repeated string errors 2; }ref的取值规则以 openapiv2.proto 中JSONSchema.ref字段的注释为准它可以是一个全限定的 proto 消息名带前导点包含完整 package如文档示例中的.example.service.v1.GenericResponse或.google.protobuf.Timestamp被引用的类型必须 import 进当前 proto 文件that type must be imported into the protofile如果ref指向的识别不出对应消息该 Ref 会原样写进生成结果the Ref will be used verbatim in the output。只对单个 RPC 生效时的写法文档指出 The annotation can also be specified per-rpc。按 RPC 生效时使用 annotations.proto 中扩展google.protobuf.MethodOptions的openapiv2_operation选项它带有与文件级相同的responsesmap结构见 openapiv2.proto 中的Operation消息。写法与文件级一致只是把responses块移到具体 rpc 的option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation)里。如果你的 proto 无法修改例如第三方服务OpenAPI 选项还可以放在外部 YAML 配置文件中通过openapi_configuration参数传入gRPC API Configuration 文档 给出了该用法与 unannotated_echo_service.swagger.yaml 这个示例文件其中展示了 file/method 两级responses的 YAML 结构。生成并验证结果用protoc生成 OpenAPI 文件命令取自 READMEprotoc -I . --openapiv2_out ./gen/openapiv2 \ your/service/v1/your_service.proto使用buf时则在buf.gen.yaml中加入protoc-gen-openapiv2插件后执行buf generate。生成后打开产出的*.swagger.json验证点有两个对应 operation 的responses中出现你配置的响应码其 schema 为$ref。文档给出的示例输出文档示例包名不同会得到不同名字是400: { description: Returned when the request is malformed., schema: { $ref: #/definitions/v1GenericResponse } },文档顶部的definitions段中包含被引用消息的完整 schema 定义$ref指向的就是该定义名。仓库自身的示例可以作为一个可核对的参照a_bit_of_everything.proto 中用json_schema: {ref: .grpc.gateway.examples.internal.proto.examplepb.ErrorResponse}配置了 500 响应其生成产物 a_bit_of_everything.swagger.json 里对应出现$ref: #/definitions/examplepbErrorResponse同一文件中的 418 响应引用枚举后生成了$ref: #/definitions/examplepbNumericEnum。注意$ref里的定义名是由消息的完全限定名推导出来的文档示例中 package 为example.service.v1时生成v1GenericResponse不要手动写定义名以ref中填写的完全限定名为准。限制与边界文件级的responses作用于该 proto 文件定义的所有 RPC只对个别方法生效要用 per-rpc 的openapiv2_operation选项。ref不是任意的 JSON 字符串占位填的是全限定消息名且消息已 import 时才会被解析为指向 definitions 的$ref填了但识别不出消息时会被原样输出需要回到 proto 检查包名和 import。该机制用于protoc-gen-openapiv2OpenAPI v2的生成路径本文不覆盖protoc-gen-openapiv3的输出格式差异两者各自的选项定义分别位于 protoc-gen-openapiv2/options/ 与 protoc-gen-openapiv3/options/。【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考