Menu
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?
788
gRPC and OpenAPI clients both calculate parameter values. Where a gRPC client uses a stub procedure to combine the parameters with the procedure signature and make the call, an OpenAPI client inserts the parameter values into the URL path template and issues an HTTP request.
OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including: Available endpoints ( /users ) and operations on each endpoint ( GET /users , POST /users ) Operation parameters Input and output for each operation.
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.
89
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!
43
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
