goswaggerprotocol-buffersgrpc-gateway

gRPC and Swagger annotation differences


I have a protocol buffer definition, which includes google.protobuf.Timestamp as part of a message. The Timestamp message is pretty simple and has the following definition:

message Timestamp {
  int64 seconds = 1;
  int32 nanos = 2;
}

So the gRPC payload comes out as a simple tuple of values as expected. However I also wanted to generate some swagger annotations for REST API for the same message, but it seems to convert the Timestamp into an RFC 3339 style string:

"timestamp": {
  "type": "string",
  "format": "date-time",
  "title": "timestamp"
}

I recently started working with protocol buffers and gRPC, so I am not sure if I am missing something here, but it seems to be an inconsistency with grpc-gateway implementation. Why would REST be a different format than the gRPC payload? Or am I missing some way to tell protoc-gen-swagger not to convert the message into a string?


Solution

  • I am not that familiar with protoc-gen-swagger itself, but I believe this is happening because of the json-proto format defined here:

    https://developers.google.com/protocol-buffers/docs/proto3#json

    It's done this way to make it more "natural" for JSON-based APIs. I don't know of any way to avoid this except by using your own type to hold the timestamp instead of google.protobuf.Timestamp. However, JSON conversion is expected to work correctly in both directions, so when the JSON is converted back to a proto message by the library, it should not cause any problems.