Grpc-gateway: Document protoc-gen-swagger

[boosh]

There's no obvious documentation on how to actually comment .proto files so they can be parsed by protoc-gen-swagger. It'd be useful if some was added.

[achew22]

The parsing should be the same as for the gateway code. Can you elaborate on what more you would be interested in having than the link in our docs that says custom option?

[boosh]

The parsing should be the same as for the gateway code.

I don't really know what you're referring to here. As an end user I was hoping not to have to look into the source.

However, I've seen from digging around in the source of this plugin that various rules are applied to comments, like:

• It'll treat the first line of a comment as the title of a swagger item, unless it ends with a period (not sure why but this isn't intuitive).
• Blank comment lines appear to be necessary to separate paragraphs.
• Subsequent paragraphs will be used as the summary or maybe description,
• etc., etc.

It'd be useful to have a guide that explicitly states all these rules along with examples so it's obvious how .proto files should be commented so that swagger files are correctly generated in terms of documentation.

[achew22]

You can always look at our kitchen sink for a fully fleshed out version of a proto. It should have one of everything.

[ensonic]

/sub.
Also, is there a way to supply some option via command line parameters or the idea to supply a skelleton swagger.spec via

option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) ...

and then let the tool overwrite/add things parsed from the proto.

[achew22]

I think subscribing to https://github.com/grpc-ecosystem/grpc-gateway/pull/521 is probably the way to go here. Is that PR what you were thinking of?