gnostic-grpc

gnostic gRPC plugin

This plugin has two functionalities:

• Conversion of an OpenAPI v3.0 API description into a description of a gRPC service that can be used to implement that API using gRPC-JSON Transcoding. gRPC services are described using the Protocol Buffers language. Continue reading this README for more information.
• Scanning OpenAPI v3 documents for equivalent gRPC service incompatibilities. For simple per file incompatibility scanning see the README file in the directory. For analysis over a set of OpenAPI documents see the README file in the directory.

OpenAPI descriptions are read and processed with gnostic, and this tool runs as a gnostic plugin.

High level overview:

Under the hood the plugin first creates a FileDescriptorSet (bookststore.descr) from the input data. Then protoreflect is used to print the output file.

How to use:

Install gnostic and the plugin before Go 1.17:

go get -u github.com/google/gnostic
go get -u github.com/google/gnostic-grpc

with Go >= 1.17:

go install github.com/google/gnostic@latest
go install github.com/google/gnostic-grpc@latest

Run gnostic with the plugin:

gnostic --grpc-out=examples/bookstore examples/bookstore/bookstore.yaml

This generates the gRPC service definition examples/bookstore/bookstore.proto.

End-to-end example

This directory contains a tutorial on how to build a gRPC service that implements an OpenAPI specification.

What conversions are currently supported?

Given an OpenAPI object following fields will be represented inside a .proto file:

Disclaimer

This is prerelease software and work in progress. Feedback and contributions are welcome, but we currently make no guarantees of function or stability.

Requirements

gnostic-grpc can be run in any environment that supports Go and the Google Protocol Buffer Compiler.

Copyright

Copyright 2019, Google Inc.

License

Released under the Apache 2.0 license.