Google gRPC Gateway : Overriding response fields?

Question

I am currently working on creating a gRPC service that uses the gRPC gateway / HTTP reverse-proxy to also offer HTTP support. I would like to follow the common conventions of Google API design.

The example I found in the Google API design guide uses google.protobuf.Empty messages for the response of delete methods/RPCs. This is fine, but when I generate a .swagger.json file from the .proto file using protoc-gen-swagger from grpc-gateway, the description of the google.protobuf.Empty message gets pulled in as the description of the response object. This is irrelevant and probably confusing for users of my API, since people using the HTTP gateway aren't using protobufs.

...
"paths": {
  "/v1/{name}": {
    "delete": {
      "summary": "Deletes a book.",
      "operationId": "DeleteBook",
      "responses": {
        "200": {
          "description": "",
          "schema": {
            "$ref": "#/definitions/protobufEmpty"
          }
        }
      },
      ...
    }
  }
},
"definitions": {
  "protobufEmpty": {
    "type": "object",
    "description": "service Foo {\n      rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);\n    }\n\nThe JSON representation for `Empty` is empty JSON object `{}`.",
    "title": "A generic empty message that you can re-use to avoid defining duplicated\nempty messages in your APIs. A typical example is to use it as the request\nor the response type of an API method. For instance:"
  }
}

I would say that this is an issue that should be resolved by the protoc-gen-swagger plugin, except that it's really doing what it's supposed to. Is there an HTTP annotation to somehow handle or override the fields in a response? If not, how do people handle this?

Petrillo

Answer 1

You could write a script that removes unwanted elements from the OpenAPI spec after it has been generated by protoc. Something like jq 'del(.definitions.protobufEmpty)' your.swagger.spec.json should work.

Unblessed

That's what I ended up doing, but I was hoping to find out about a better fix or at least draw the maintainers' attention to this issue. – Petrillo