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.
Under the hood the plugin first creates a FileDescriptorSet (bookststore.descr) from the input
data. Then protoreflect is used to print the output file.
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.
This directory contains a tutorial on how to build a gRPC service that implements an OpenAPI specification.
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 |
This is prerelease software and work in progress. Feedback and contributions are welcome, but we currently make no guarantees of function or stability.
gnostic-grpc can be run in any environment that supports Go and the Google Protocol Buffer Compiler.
Copyright 2019, Google Inc.
Released under the Apache 2.0 license.