protoc-gen-swagger: Implement Response Header(s) object, Implement Field Enum,Example&Format attributes

[elijah-roberts]

🚀 Feature

My team would like to auto-generate swagger/openapi docs from our proto files, however there are certain features that are missing that we would need in order to move away from manually managed openapi docs:

• Headers/Header Object support - We currently return an header for all success, and failure responses and need to be able to define this via the grpc.gateway.protoc_gen_swagger.options.openapiv2_operation Responses Headers Object.
  

• grpc.gateway.protoc_gen_swagger.options.openapiv2_field example attribute support (cleaner than example_string)

• grpc.gateway.protoc_gen_swagger.options.openapiv2_field format attribute support
  

• grpc.gateway.protoc_gen_swagger.options.openapiv2_field enum attribute support
  

[johanbrandhorst]

Thanks for your interest, and I see you already took a stab at fixing this in #1730, however I had one small comment. The example_string is as it is because we couldn't remove the example field, I think we want to make any new example fields strings from the start. The example field in our v2 branch is already a string.

Also, generally we've not been accepting new work on the v1 version of the gateway at this point (the master branch), because we want to encourage users to move to v2, whose stable release is imminent. However, since you've already done all the work I think we can allow it in this case, though please be aware that we'll ask you to cherry-pick the changes across to v2 as well.

[elijah-roberts]

@johanbrandhorst The original goal of this issue was to enable auto-generation of required open api items via implementing missing annotation objects.

I found another object that we need to implement for our use case, which is the parameters object, on the operations annotation. Currently only body parameters are implemented.

Do you want me to put this into a separate issue, and PR or include it with the existing one? I have the majority of the logic working locally, I am just implementing some more tests, and validation functions.

[johanbrandhorst]

If we could do it in a separate PR I would appreciate it, thank you.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[johanbrandhorst]

I think this is done?

[elijah-roberts]

Yes, it was merged to both v1 and v2

[johanbrandhorst]

Thanks!