Support Service doc comments for OpenApi/Swagger generation

[seanlaff]

For methods we can control the OpenAPI title/description via comments

// Update a book
//
// This method updates a book
 rpc UpdateBook(UpdateBookRequest) returns (Book) { 
   option (google.api.http) = { 
     patch: "/v1/{book.name=publishers/*/books/*}" 
     body: "book" 
   }; 
 } 

However, I can't find any documentation for doing the same at the service level, and I don't see it in ABitOfEverything.proto. I'd like to do

 // Book
//
// Methods of interacting with books
service BookService {
}

and have it function as if I did

service BookService {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_tag) = {
    name: "Book"
    description: "Methods of interacting with books"
  }
}

[johanbrandhorst]

HI, thanks for your issue! I can't tell if this is a straightforward mapping, is a openapiv2_tag analogous to a service? I'd be happy to look at a PR that experiments with this idea to see if it makes sense.

[seanlaff]

Yup, that is the distinction the generator currently makes. Of note is that all the methods attached to a service need to point to the renamed openapiv2_tag, and not the original name, else they won't render properly in the swagger UIs. I imagine a first pass at this issue may run into the same issues as described in https://github.com/grpc-ecosystem/grpc-gateway/issues/3829#issuecomment-1994218163