30

I have an API generated from protobuf, and I would like to generate documentation conforming to the OpenAPI 3 spec. I've looked at a number of utilities but I haven't found a combination that works.

Does anyone know of a path from protobuf to OpenAPI 3 that I can follow?

KHilse
  • 301
  • 1
  • 3
  • 4

3 Answers3

6

I searched for the answer recently and found this package: protobuf2swagger It can be run in CLI with a js config file required. This packaged solved my problem.

Dharman
  • 30,962
  • 25
  • 85
  • 135
NamND
  • 61
  • 1
  • 3
4

Google has a repository on GitHub to do exactly that. It contains examples for OpenAPI v3 (and v2) on how the equivalent protobuf code should look like.

Here is a medium article that explains end to end gRPC + HTTP (using protobuf and swagger respectively) server implementation and documentation, in a step by step fashion. It is an OpenAPI v2 example, but similar concepts apply to OpenAPI v3.

There are other repositories that can do the same, but I would recommend to use the source code that is actually coming from the very source. :)

Hope this helps!

Krishna Birla
  • 332
  • 2
  • 10
  • 18
    The first and last links are for converting OAS to protos/gRPC, not protos/gRPC to OAS. The middle link is an article about https://github.com/grpc-ecosystem/grpc-gateway which does to gRPC to OAS, though it's OAS 2. – smparkes Aug 31 '20 at 19:17
  • I wish there is a way to integrate grpc-gateway in Quarkus /java project. – Espresso Oct 08 '20 at 16:17
  • 2
    Unfortunately, none of these links answer the OP's question, which is very specific (I'm also looking for an answer.) – luis.espinal Aug 01 '22 at 12:45
4

Looks like protoc-gen-openapi app, from gnostic, is what you were looking for. But it seems abandoned and not working.

Have no idea if it works.

ubombi
  • 1,115
  • 2
  • 15
  • 30