Fix #1117: Support response examples.

[jgiles]

Add support for examples in operation annotation responses. Merge
custom response data into the default 200 response.

[codecov-io]

Codecov Report

Merging #1124 into master will increase coverage by 0.05%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master    #1124      +/-   ##
==========================================
+ Coverage   53.63%   53.68%   +0.05%     
==========================================
  Files          42       42              
  Lines        4182     4187       +5     
==========================================
+ Hits         2243     2248       +5     
  Misses       1692     1692              
  Partials      247      247

Impacted Files	Coverage Δ
protoc-gen-swagger/genswagger/template.go	56.37% <100%> (+0.2%)	⬆️

---

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 193538d...c1cf149. Read the comment docs.

[johanbrandhorst]

This looks great to me, I had a question about the swagger.yaml change, but it's not a blocker. I was wondering if we could add a section to the docs explaining how a user can use this? Thanks for taking the time to implement this!

[jgiles]

Where in the documentation do you think this should live? I did a quick look-through, and wasn't sure where to put it.

For what it's worth, I generally look at a_bit_of_everything.proto when I want to see what I can do and how :-)

[johanbrandhorst]

Where in the documentation do you think this should live? I did a quick look-through, and wasn't sure where to put it.

I think we could do with a section on customising the swagger output. It could just be including some links to the big protofile. I appreciate your time is valuable so don't worry about writing too much.

For what it's worth, I generally look at a_bit_of_everything.proto when I want to see what I can do and how :-)

Yeah I often tell users this and it's not obvious enough to beginners. We should've had a link to this file for a long time already.

[jgiles]

@johanbrandhorst I took a stab at some documentation improvements. They do not specifically reference this new feature, but they highlight that this kind of thing is possible and point at a_bit_of_everything.proto

[johanbrandhorst]

Great work on this! Really appreciate the thoroughness and responsiveness.

[jgiles]

Thank you for being so responsive! You're doing great work as a maintainer in the ecosystem - we've seen that both in this project and in others (e.g. https://github.com/grpc-ecosystem/go-grpc-middleware ).