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:

Object	Fields	Supported
OpenAPI object
	openapi	No
	info	No
	servers	No
	paths	Yes
	components	Yes
	security	No
	tags	No
	externalDocs	No

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.