Add missing documentation for openapiv2 proto definition

[bvwells]

Add missing documentation for openapiv2 proto definition.

[bvwells]

@johanbrandhorst - this PR adds some missing documentation for open API fields. I've taken the OpenAPI spec definitions for them.

[bvwells]

Guess that I will need to regenerate some code before completing. Will push updates.

[johanbrandhorst]

Please see https://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md for the regeneration steps

[bvwells]

Yep, on it. Just had to setup access to docker.pkg.github.com.

[bvwells]

All re-generated now.

[codecov-commenter]

Codecov Report

Merging #1375 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1375   +/-   ##
=======================================
  Coverage   54.14%   54.14%           
=======================================
  Files          42       42           
  Lines        4375     4375           
=======================================
  Hits         2369     2369           
  Misses       1750     1750           
  Partials      256      256           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2d9c2c0...619eda5. Read the comment docs.

[johanbrandhorst]

This is great, thanks! My only concern is with the use of the phrase Required, if it will confuse users. We do have defaults for all the required values, and any of these uses are additive to the defaults. What do you think?

[johanbrandhorst]

Suggested change

	// Required Provides the version of the application API (not to be confused
	// Required. Provides the version of the application API (not to be confused

[bvwells]

Agreed, I was a little unsure about adding this as obviously there is a difference between what the swagger spec defines as required and what is required for protoc-gen-swagger. I'll remove the required statement. I guess we could document the defaults at some point.

[bvwells]

It looks like there are a number of other descriptions in the proto definition which look like they have been copied from the open api spec verbatim with 'required'. Do you think we should also remove this?

[johanbrandhorst]

Haha, yeah, just left a comment to this effect.

[bvwells]

I've not removed all the other instances of required.

[johanbrandhorst]

Could we remove the other Required. as well while we're here please?

[johanbrandhorst]

Thanks a ton, this is great! Could you please cherry pick this against v2?

[bvwells]

Added PR #1378. Thanks for the review and merge!