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 Swift.
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.
This is prerelease software and work in progress. Feedback and contributions are welcome, but we currently make no guarantees of function or stability.
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
[Optional] Build and run the gnostic compiler generator. This uses JSON schemas to generate Protocol Buffer language files that describes 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 directories named OpenAPIv2, OpenAPIv3, and discovery.
go install ./generate-gnostic generate-gnostic --v2 generate-gnostic --v3 generate-gnostic --discovery
Generate Protocol Buffer support code. This step requires a local installation of protoc, the Protocol Buffer Compiler, and the Go protoc plugin. You can get protoc here. You can install the plugin with this command:
go get github.com/golang/protobuf/protoc-gen-go
Then use the following to compile the gnostic Protocol Buffer models:
go install .
Run gnostic. This sample invocation creates a file in the current directory named "petstore.pb" that 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.
go install ./apps/report report petstore.pb
gnostic supports plugins. Some are already implemented in the
pluginsdirectory. Others, like gnostic-go-generator, are separated into their own repositories.
Copyright 2017, Google Inc.
Released under the Apache 2.0 license.
You may find interesting
Improved testing and style compliance - 2020-01-31 18:58:32
All tests are run by CI. Package directory names are lowercased to match Go style guidance.
OpenAPI 3.1 support - 2020-01-24 20:31:02
Also streamlined release (removed Swift code for release elsewhere) and added plugin development helpers.
Support for Go Modules - 2019-08-15 21:30:19
This point release adds go.mod and go.sum files to provide Go module support.
v0.3.0 - 2019-06-14 23:29:45
Bug fixes, enhancements to the OAS v3 surface and removal of
gnostic-go-generator (moved to https://github.com/googleapis/gnostic-go-generator)
Initial release - 2018-05-19 19:10:56
Tagged for initial use in Kubernetes and Istio.
OpenAPI 3.0.1 support. - 2018-05-19 19:06:30
This release updates the OpenAPIv3 Protocol Buffer models to OpenAPI 3.0.1 using a JSON schema generated by scraping the text of the official OpenAPI 3.0.1 specification.
The scraper and generated JSON schema are gnostic-specific and are not endorsed by the OpenAPI Technical Steering Committee, which has not yet released or approved a JSON Schema for OpenAPI v3.