[WIP] feat: adds Headers to Operation for specifying request headers

[amitavaghosh1]

References to other Issues or PRs

Fixes#2932

Brief description of what is fixed or changed

Adding header definition to Operation. To be used to render request headers as in openapi v2.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[johanbrandhorst]

I'm not sure what's going here but we cannot make this many changes here, it will break all existing users. Please constrain yourself to additions only.

[amitavaghosh1]

Hi @johanbrandhorst , sorry, I got caught up in some work. Could you please elaborate a bit more. Do you mean, inside Operations we cannot add any more fields?
I have removed the other stuff and kept only headers for now.

[johanbrandhorst]

The fields in this msaage map to the fields in https://swagger.io/specification/v2/#operation-object. As far as I can tell, headers does not belong here, but in the parameter object: https://swagger.io/specification/v2/#parameter-object. Naturally, we don't actually allow the user to specify the parameter object, since it's entirely inferred from the request parameters in the protobuf file. Maybe you could define a very shallow parameter type and we can allow the user to only specify headers? Still not sure it's a good idea though.

[amitavaghosh1]

Okay, I will try that. It makes sense. Sure, I will have maybe only the bare minimum and not everything in the spec. for the Parameter object

[krak3n]

I'm completely new to this proto to openapiv2 thing, but if we want to avoid users explicitly setting the parameter object and only allow them to define header parameters would it not be safer to add a headers field in the operation message which can be used to add the needed parameters?

[krak3n]

I guess it would end u[ be something like this:

message Operation {
  // existing fields
  Parameters parameters = 14;
}

message Parameters {
  repeated HeaderParameter headers = 1;
}

message HeaderParameter {
  string name = 1;
  // etc etc
}

This ends up looking like this in the operation:

service FooService {
  rpc CreateFoo(CreateFooRequest) returns (CreateFooResponse) {
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      parameters: {
        headers: {
          name: "Authorization";
          description: "Basic Auth";
          required: true;
        };
        headers: {name: "X-Thing"};
        headers: {name: "X-Other"};
      };
    };
  }
}

[krak3n]

Any news on this one, I am also in need of it 😄

[krak3n]

Do you mind if I take this over @amitavaghosh1 and open a new PR? I have a working PoC since I'm also in need of this feature.

[johanbrandhorst]

Please feel free Chris :). I can close this one if we merge the other one.

[krak3n]

Opened #3010 which I think works 😅

[johanbrandhorst]

Superceded by #3010