Feature: Items support on OpenAPI V2 Responses

[krak3n]

Feature 🚀

Adds support for array items on Open API V2 response objects. This is currently not supported when disable_default_responses is true.

This allows users to define array response objects, for example:

message Foo {
  string bar = 1;
}

message ListFoosResponse {
  repeated Foo foos = 1;
}

service FooService {
  rpc ListFoos(google.protobuf.Empty) returns (ListFoosResponse) {
    option (google.api.http) = {
      get: "/foo";
      response_body: "foos"; // This will not be handled when disable_default_responses=true
    };

    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      responses: {
        key: "200",
        value: {
          description: "List Foos"
          schema: {
            json_schema: {
              type: ARRAY;
              items: {ref: ".some.package.v1.Foo"};
            }
          }
        };
      };
    };
  };
};

This will generate the following yaml when disable_default_responses=true

  /foo:
    get:
      summary: List Foos.
      operationId: ListFoos
      responses:
        "200":
          description: List Foos
          schema:
            type: array
            items:
              $ref: '#/definitions/some.package.v1.Foo'

See examples here on the OpenAPI V2 spec page.

TODO

• Documentation
• Test Case

[krak3n]

Before I went any further adding tests / docs I wanted to get your thoughts on this one @johanbrandhorst 😄

[johanbrandhorst]

Hi Chris, thanks for the PR! I understand we already allow users to specify custom responses, but this now adds the ability to specify a custom response where the outermost type is an array, is that correct? If so, this isn't so much about how this feature interacts with the disable_default_responses feature, but rather just about adding this functionality, correct? If so, should we rewrite the proto file comment to focus more on that?

[johanbrandhorst]

Any reason we shouldn't just make this 19 and hoist it up to the comment above?