Support request header parameters

[krak3n]

Fixes #2932

Feature 🚀

Adds support for optional HTTP request header parameters to be defined on method operations, for example:

service FooService {
  rpc CreateFoo(CreateFooRequest) returns (CreateFooResponse) {
    option (google.api.http) = {
      post: "/foo"
      body: "*"
    };

    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "Create a new foo.";
      parameters: {
        headers: {
          name: "Authorization";
          description: "Basic Auth";
          required: true;
        };
      };
    };
  }
}

This should generate the following yaml:

paths:
  /v2/foo:
    post:
      summary: Create a new foo.
      operationId: CreateFoo
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/CreateFooResponse'
      parameters:
        - name: foo
          in: body
          required: true
          schema:
            $ref: '#/definitions/CreateFooRequest'
        - name: Authorization
          in: header
          required: false

Changes

• New protocol buffer definitions for HTTP Header Parameters
• New loop in applyTemplate which loops over header parameters if defined and > 0 which builds and appends the header parameters. to the existing generated parameters.
• Test cases for the above

[johanbrandhorst]

Thanks a lot for looking at this! Some minor comments, but in addition to those please add a section to the docs about this ✨ new feature ✨. This sort of thing has been requested a lot, thanks for helping bring it over the line. Please ensure the docs make it clear that adding headers to your schema via these annotations does nothing to change the behavior of the gateway and that these annotations should only be coupled with custom header parsing behavior in the application. Also that adding header parameters can chance the forward and backward compatibility guarantees of the schema. Thanks!

[johanbrandhorst]

The code changes look fine but could you please add something to the docs as well? Also, it looks like you need to regenerate the files again 😁.

[krak3n]

@johanbrandhorst added documentation & regenerated the go code. I noticed when I run buf generate a load of swagger json also gets generated, does that need to be committed too?

[johanbrandhorst]

@johanbrandhorst added documentation & regenerated the go code. I noticed when I run buf generate a load of swagger json also gets generated, does that need to be committed too?

Just running buf generate will not generate the files the way we want, you'll need the command in the CONTRIBUTING.md file, which it looks like you're aware of. If there were more files needed, our generate job should detect it. Looks good from this side!

[johanbrandhorst]

LGTM

[johanbrandhorst]

I think this is one of the most user requested features, so thank you for this great contribution! I'll consider making a new release shortly.

[amitavaghosh1]

Thanks @krak3n

[imrenagi]

hi @amitavaghosh1 @johanbrandhorst if I have a HTTP header that is used across all API (not for security), is there any way to use $ref on the endpoint parameter? I cant find how to define the parameters definition yet. Please let me know if you have any pointers. thanks!

something like this in swagger.

parameters:
  shardId:  
    in: header
    name: x-something-something
    required: false
    type: string

paths:
  /users:
    get:
      summary: Gets a list of users.
      parameters:
        - $ref: '#/parameters/shardId'

I was thinking about doing such thing on the operation

service UserService {
  rpc Get(Req) returns (Res) {
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      parameters: {
        headers: {
           { ref: "<reference to shared definition for header>" }
        };
      };
    };
  }
}