Issue with google.protobuf.Empty representation in swagger file

[burov]

The gRPC-Gateway project is maintained by volunteers in their spare time. Please follow these troubleshooting steps before submitting an issue.

• Check if your issue has already been reported (https://github.com/grpc-ecosystem/grpc-gateway/issues).
• Update your protoc to the latest version.
• Update your copy of the grpc-gateway library to the latest version from github:

  go get -u github.com/grpc-ecosystem/grpc-gateway

• Delete the protoc-gen-grpc-gateway and protoc-gen-swagger binary from your PATH,
  and reinstall the latest versions:

  go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
  go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger

I still have a problem!

Steps you follow to reproduce the error:

Add google.protobuf.Empty as your response message
and generate swagger file

What did you expect to happen instead:

I want see whole comment as description field in protobufEmpty definition but instead text before first blank line add to title and remaining text to description it prevent two bad view in https://editor.swagger.io/ because title rendered as definition name.

Is that expected behavior ? Or how i can fix it ?

[johanbrandhorst]

It is indeed expected behaviour, the JSON definition of google.protobuf.Empty is an empty object. If you want to have some text there you may have to define your own type.

[burov]

@johanbrandhorst I understand it, but comment before type rendered to Definition as description and title, on https://editor.swagger.io/ title always rendered as definition name and.

// A generic empty message that you can re-use to avoid defining duplicated
// empty messages in your APIs. A typical example is to use it as the request
// or the response type of an API method. For instance:
//
//     service Foo {
//       rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
//     }
//
// The JSON representation for `Empty` is empty JSON object `{}`.
message Empty {}

First part(Before first blank line) of comment will be stored in field title

// A generic empty message that you can re-use to avoid defining duplicated
// empty messages in your APIs. A typical example is to use it as the request
// or the response type of an API method. For instance:

Second part(After first blank line) will be stored in field description

//     service Foo {
//       rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
//     }
//
// The JSON representation for `Empty` is empty JSON object `{}`.

Swagger UI replace definition name and render title field instead of it, and it looks ugly

My question was is this some contract all before blank line we render to title and remain as description on my opinion i think whole comment must rendered as description.
Thank you.

[johanbrandhorst]

The Title and Description are indeed gathered from the first line (before double newline) and subsequent content by default. It's possible to overrwrite with

// MyMessage is a custom message.
message MyMessage {
  option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
    json_schema: {
      title: "MyMessage"
      description: "A custom message."
    }
  };
  // MyString
  //
  // A string.
  string my_string = 1;
}