This repository contains a Go command line tool which converts JSON and YAML OpenAPI descriptions to and from equivalent Protocol Buffer representations.
Protocol Buffers provide a language-neutral, platform-neutral, extensible mechanism for serializing structured data. gnostic's Protocol Buffer models for the OpenAPI Specification can be used to generate code that includes data structures with explicit fields for the elements of an OpenAPI description. This makes it possible for developers to work with OpenAPI descriptions in type-safe ways, which is particularly useful in strongly-typed languages like Go and Dart.
gnostic reads OpenAPI descriptions into these generated data structures, reports errors, resolves internal dependencies, and writes the results in a binary form that can be used in any language that is supported by the Protocol Buffer tools. A plugin interface simplifies integration with API tools written in a variety of different languages, and when necessary, Protocol Buffer OpenAPI descriptions can be reexported as JSON or YAML.
Feedback and contributions are welcome! Until there is a 1.0 release, please consider this prerelease software and work in progress. To ensure stable builds, we request that dependent projects always refer to tagged releases of gnostic.
Installation and Getting Started
The following instructions are for installing gnostic using Go modules, supported by Go 1.11 and later.
Get this package by downloading it with
git clone https://github.com/googleapis/gnostic cd gnostic
Verify that you have a local installation of
protoc. You can get protoc here.
Build gnostic with
make. This uses go generate to build support code including code generated by
protocand the Go protoc plugin, which is automatically downloaded from github.com/golang/protobuf by the COMPILE-PROTOS.sh script. This also builds all plugins and associated tools in this repo.
Verify gnostic with
make test. These tests are run by gnostic's continuous integration, so you should expect them to pass for all release versions.
Run gnostic. This sample invocation creates a file in the current directory named
petstore.pbthat contains a binary Protocol Buffer description of a sample API.
gnostic --pb-out=. examples/v2.0/json/petstore.json
You can also compile files that you specify with a URL. Here's another way to compile the previous example. This time we're creating
petstore.text, which contains a textual representation of the Protocol Buffer description. This is mainly for use in testing and debugging.
gnostic --text-out=petstore.text https://raw.githubusercontent.com/googleapis/gnostic/master/examples/v2.0/json/petstore.json
For a sample application, see apps/report. This reads a binary Protocol Buffer encoding created by gnostic.
go install ./apps/report ## automatically installed by the top-level Makefile report petstore.pb
gnostic also supports plugins. gnostic's plugin interface is modeled on
protoc's plugin.proto and is described in plugins/plugin.proto. Several plugins are implemented in the
pluginsdirectory. Others, like gnostic-grpc and gnostic-go-generator, are published in their own repositories. One such plugin is gnostic-vocabulary, which produces a summary of the word usage in an APIs interfaces. You can run
gnostic-vocabularywith the following:
gnostic examples/v2.0/json/petstore.json --vocabulary_out=.
This will produce files named
examples/v2.0/json. For the format of
vocabulary.pb, see metrics/vocabulary.proto.
[Optional] A large part of gnostic is automatically-generated by the generate-gnostic tool. This uses JSON schemas to generate Protocol Buffer language files that describe supported API specification formats and Go-language files of code that will read JSON or YAML API descriptions into the generated protocol buffer models. Pre-generated versions of these files are checked into the openapiv2, openapiv3, and discovery directories. You can regenerate this code with the following:
go install ./generate-gnostic generate-gnostic --v2 generate-gnostic --v3 generate-gnostic --discovery
Copyright 2017-2020, Google LLC.
Released under the Apache 2.0 license.