A compiler for API described by the OpenAPI Specification with plugins for code generation and other API support tasks.
Swift Go Other
Clone or download
timburks Merge pull request #92 from googleapis/issue-82
Modify generated ToRawInfo methods to always include required fields.
Latest commit 48a0ece May 20, 2018
Permalink
Failed to load latest commit information.
OpenAPIv2 Modify generated ToRawInfo methods to always include required fields. May 20, 2018
OpenAPIv3 Modify generated ToRawInfo methods to always include required fields. May 20, 2018
apps Updating v3 schema and models for OpenAPI 3.0.1. May 19, 2018
compiler Fix incorrect caching of parsed discovery documents. Jan 5, 2018
discovery Rework constructors of yaml.MapItem to enable future line-number trac… Dec 9, 2017
examples Modify generated ToRawInfo methods to always include required fields. May 20, 2018
extensions Updates to replace old 'openapic' with 'gnostic'. Dec 10, 2017
generate-gnostic Modify generated ToRawInfo methods to always include required fields. May 20, 2018
jsonschema Fix build failure in tools/j2y2j Jan 26, 2018
jsonwriter golint-driven cleanup of main packages. Jul 17, 2017
linters Simplify Swift linter, add README Feb 17, 2018
plugins Fix problem reported in GitHub issue 85. May 19, 2018
printer Modify generated ToRawInfo methods to always include required fields. May 20, 2018
surface Modify generated ToRawInfo methods to always include required fields. May 20, 2018
test Modify generated ToRawInfo methods to always include required fields. May 20, 2018
tools Add comments for godoc. Mar 24, 2017
.gitignore Add linter plugin to check for array responses Feb 15, 2018
.travis-install.sh reenable Swift tests, update to Swift 4. Sep 4, 2017
.travis.yml gnostic-go-generator improvements Jan 26, 2018
COMPILE-PROTOS.sh Rework constructors of yaml.MapItem to enable future line-number trac… Dec 9, 2017
CONTRIBUTING.md Initial commit Oct 26, 2016
LICENSE Rename LICENSE file. Nov 2, 2016
Makefile Reworked plugin architecture to pass strongly-typed documents. Sep 4, 2017
README.md Updates to replace old 'openapic' with 'gnostic'. Dec 10, 2017
gnostic.go Measure plugin runtimes. Feb 17, 2018
gnostic_test.go Modify generated ToRawInfo methods to always include required fields. May 20, 2018

README.md

Build Status

⨁ gnostic

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.

gnostic compilation code and OpenAPI Protocol Buffer models are automatically generated from an OpenAPI JSON Schema. Source code for the generator is in the generate-gnostic directory.

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 can be run in any environment that supports Go and the Google Protocol Buffer Compiler.

Installation

  1. Get this package by downloading it with go get.

     go get github.com/googleapis/gnostic
    
  2. [Optional] Build and run the compiler generator. This uses the OpenAPI JSON schema to generate a Protocol Buffer language file that describes the OpenAPI specification and a Go-language file of code that will read a JSON or YAML OpenAPI representation into the generated protocol buffers. Pre-generated versions of these files are in the OpenAPIv2 directory.

     cd $GOPATH/src/github.com/googleapis/gnostic/generate-gnostic
     go install
     cd ..
     generate-gnostic --v2
    
  3. [Optional] Generate Protocol Buffer support code. A pre-generated version of this file is checked into the OpenAPIv2 directory. 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 -u github.com/golang/protobuf/protoc-gen-go
    

Then use the following to recompile the Gnostic Protocol Buffer models:

    ./COMPILE-PROTOS.sh
  1. [Optional] Rebuild gnostic. This is only necessary if you've performed steps 2 or 3 above.

     go install github.com/googleapis/gnostic
    
  2. Run gnostic. This will create 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
    
  3. 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/petstore.json
    
  4. For a sample application, see apps/report.

     go install github.com/googleapis/gnostic/apps/report
     report petstore.pb
    
  5. gnostic supports plugins. This builds and runs a sample plugin that reports some basic information about an API. The "-" causes the plugin to write its output to stdout.

     go install github.com/googleapis/gnostic/plugins/gnostic-go-sample
     gnostic examples/v2.0/json/petstore.json --go-sample-out=-
    

Copyright

Copyright 2017, Google Inc.

License

Released under the Apache 2.0 license.