如何在gRPC-Gateway的OpenAPIv2配置中添加响应示例？

问题描述 #

我有如下gRPC方法：

rpc RpcMethod(RpcRequest) returns (RpcResponse) {
    option (google.api.http) = {
      get: "/rpcMethod"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      responses: {
        key: "200",
        value: {
          description: "OK";
          schema: {
            json_schema: {ref: ".rpc.RpcResponse"}
          }
        }
        examples : {TRYING_TO_FIGURE_OUT_HERE}
      };
    };
  }

在OpenAPI规范中，我希望添加响应示例，因为当前生成的SwaggerUI仅显示RpcResponse结构体，但不清楚如何编写examples字段的代码。从openapiv2.proto中可见编号为4的examples字段（定义如下），但无法使其生效，不确定是否为未启用的保留字段：

message Response {
  // `Description` is a short description of the response.
  // GFM syntax can be used for rich text representation.
  string description = 1;
  // `Schema` optionally defines the structure of the response.
  // If `Schema` is not provided, it means there is no content to the response.
  Schema schema = 2;
  // `Headers` A list of headers that are sent with the response.
  // `Header` name is expected to be a string in the canonical format of the MIME header key
  map<string, Header> headers = 3;
  // `Examples` gives per-mimetype response examples.
  map<string, string> examples = 4;
  // Custom properties that start with "x-" such as "x-foo" used to describe
  // extra functionality that is not covered by the standard OpenAPI Specification.
  map<string, google.protobuf.Value> extensions = 5;
}

解决方案 #

examples字段并非保留字段，只要按照map<string, string>的格式正确配置就能生效，以下是具体实现步骤：

1. 明确字段格式要求 #

examples是按MIME类型映射的转义JSON字符串：

• Key：必须是合法的MIME类型（如application/json）
• Value：对应MIME类型的示例内容，需要转义为单行字符串（避免protoc编译报错）

2. 完整配置示例 #

假设RpcResponse的定义为：

message RpcResponse {
  string message = 1;
  int32 code = 2;
}

修改后的gRPC方法配置如下：

rpc RpcMethod(RpcRequest) returns (RpcResponse) {
    option (google.api.http) = {
      get: "/rpcMethod"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      responses: {
        key: "200",
        value: {
          description: "OK";
          schema: {
            json_schema: {ref: ".rpc.RpcResponse"}
          }
          // 添加application/json类型的响应示例
          examples: {
            key: "application/json"
            value: "{\"message\": \"操作成功\", \"code\": 200}"
          }
        }
      };
    };
  }

3. 多MIME类型示例配置 #

如果需要支持多种格式的示例，可以添加多个examples条目：

examples: {
  key: "application/json"
  value: "{\"message\": \"success\", \"code\": 200}"
}
examples: {
  key: "application/xml"
  value: "<RpcResponse><message>success</message><code>200</code></RpcResponse>"
}

4. 验证生效 #

重新编译proto文件后，生成的OpenAPI规范中会包含对应的examples节点，Swagger UI会自动加载并展示示例内容，而不再只显示结构体定义。

内容的提问来源于stack exchange，提问作者Matt Moon