来自 proto openapiv2 规范的响应示例

Question

假设我有一个如下的rpc方法

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 结构。 但是，尚不清楚示例应该如何编码

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
  // See: https://golang.org/pkg/net/textproto/#CanonicalMIMEHeaderKey
  map<string, Header> headers = 3;
  // `Examples` gives per-mimetype response examples.
  // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#example-object
  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.
  // See: https://swagger.io/docs/specification/2-0/swagger-extensions/
  map<string, google.protobuf.Value> extensions = 5;
}

在 openapiv2.proto 中，有一个示例字段，标记为数字 4，如上所示。 然而我就是无法让这个领域发挥作用。它是否应该像某些保留字段一样不被使用？ 官方文档和相关的 github 页面对于这种特定情况并没有太大帮助。 如果有人可以向我展示解决此问题的方法，我将不胜感激！

Answer 1

您可以在

.rpc.RpcResponse

定义中添加示例。 我为下面的描述字段添加了一个示例：

import "protoc-gen-openapiv2/options/annotations.proto";

message Response {
    // `Description` is a short description of the response.
    // GFM syntax can be used for rich text representation.
    string description = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        example: "\"my description example\""
    }];
}