Moving to gRPC + REST + OpenAPI v3

[aeneasr]

The purpose of this discussion is to collect knowledge around gRPC, REST, OpenAPI v3. I did a spike trying to implement gRPC along with gRPC-gateway for REST support, and use gRPC-gateway to generate Swagger / OpenAPI v3.

The following things have been found:

• grpc-gateway supports custom annotations for fields, see: https://grpc-ecosystem.github.io/grpc-gateway/docs/mapping/customizing_openapi_output/
• grpc-gateway does not seem to support discriminators. gRPC oneof will render all options to Swagger.
• support for openapi v3.0 is not to be expected, given the amount of work involved.
• polymorphism (initial reason for the spike) is not supported in grpc-gateway. Instead it expects different fields to be set.

One can use buf to run the plguins. See the spike buf.gen.yaml config!

[rauanmayemir]

While I like the idea of OpenAPI, the actual API bindings are not pleasant to work with. With gRPC, we've been enjoying the developer experience so far.

We've been validating gRPC-Web for our internal APIs and it works great. (basically, we send binary payload to gRPC services over HTTP/1.1 from the browser)

I suppose, JSON transcoding would be another good approach to explore for public APIs: https://cloud.google.com/endpoints/docs/grpc/transcoding

[aeneasr]

Thank you for the report! I agree, I think most generated OpenAPI Generator code is terrible. The Go client alone had many, many issues. We are still looking into this, but it is quite hard to switch to pure gRPC because of web clients. If you come along a better code generator than the OpenAPI ones, please let me know!