Skip to content

A gnostic plugin that converts an OpenAPI API description into a description of a gRPC service that can be used to implement that API using gRPC-JSON Transcoding.

License

Notifications You must be signed in to change notification settings

google/gnostic-grpc

Go Actions Status Go Report Card Test Coverage

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:

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.

About

A gnostic plugin that converts an OpenAPI API description into a description of a gRPC service that can be used to implement that API using gRPC-JSON Transcoding.

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Packages

No packages published