proto file to openapi

[kotyara85]

Hello, I have proto file which I want to convert to openapi3 spec. Is there a way to do that? Thank you

[morphar]

Yes there is :) proto-gen-openapi

It currently has a bug in the latest release - you can use master for now:

go get github.com/google/gnostic@master
go install github.com/google/gnostic/apps/protoc-gen-openapi@master

[morphar]

There's also a pull request: #261, that updates some google.protobuf.Empty and google.protobuf.Struct handling. It's not as fully featured as the grpc-gateway's proto -> openapi, but I like this one better. It converts to OpenAPI v3, where grpc-gateway's converter converts to OpenAPI v2. And it seems to handle some stuff better by default, though grpc-gateway's converter can be customized more.

[jeffsawatzky]

@kotyara85 / @timburks I think this can be closed now?

[korneliaWatson]

Hi, this is a task I'm currently trying to achieve. Unfortunately, unsuccessfully. I get openapi.yaml file, but it's 'empty':

# Generated with protoc-gen-openapi
# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi

openapi: 3.0.3
info:
    title: ""
    version: 0.0.1
paths: {}
components:
    schemas: {}

Would it be possible to get some step-by-step instructions on how a conversion from proto to openapi should be executed?

Thank you.

[dkoukoul]

I am having the exact same issue, I have tried with several proto sample files and keep getting an empty openapi.yaml file. No other output from the protoc command.

[dkoukoul]

I am having the exact same issue, I have tried with several proto sample files and keep getting an empty openapi.yaml file. No other output from the protoc command.

I found the issue with my proto file, although I had a service declared it was missing the option (google.api.http) = {...} once I added that to the rpcs the generator worked. Maybe it would be useful for the protoc-gen-openapi to produce a comment when it finds an rpc that is missing the minimum expected fields/options

[kotyara85]

@dkoukoul can you share how do you convert proto to openapiv3, please? Thanks!

[jeffsawatzky]

@kotyara85 as @dkoukoul mentioned, you need to annotate your rpc methods with the google.api.http options. The protoc-gen-openapi plug-in uses these to detect which rpc methods will be mapped to http endpoints (using something like envoy or gRPC gateway).

https://github.com/google/gnostic/tree/main/cmd/protoc-gen-openapi

https://github.com/google/gnostic/blob/main/cmd/protoc-gen-openapi/examples/tests/rpctypes/message.proto

[kotyara85]

Thanks @jeffsawatzky, I figure that out. Btw, does this generator is capable of generating security requirements? I used to use grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation with openapi v2. Thanks!

[jeffsawatzky]

@kotyara85 yes, see this example here

https://github.com/google/gnostic/blob/main/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/message.proto

[kotyara85]

@jeffsawatzky That worked!

Found one more problem If proto has type int64, it will get converted as string in yaml, that doesn't happen with int32 type Thanks

[jeffsawatzky]

@kotyara85 that isn't a bug. That is how gRPC/protocol buffers serialize int64 due to ecmascript's lack of 64bit integer support.

See the proto guides on how each proto type gets mapped to a ecmascript type. https://protobuf.dev/programming-guides/proto3/#json