gnostic

This repository contains a Go command line tool which reads OpenAPI descriptions in JSON or YAML formats and writes equivalent Protocol Buffer representations. Protocol Buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data.

gnostic reads OpenAPI descriptions into Protocol Buffer representations, 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.

Code generated by the Protocol Buffer tools 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. This is particularly useful in strongly-typed languages like Go and Swift.

gnostic compilation code and the OpenAPI Protocol Buffer representation are automatically generated from the OpenAPI JSON Schema. Source code for the generator is in the generator 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/generator
    go build
    cd ..
    ./generator/generator
   

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. You can get protoc here.

    ./COMPILE-PROTOS.sh
   

4. [Optional] Rebuild gnostic. This is only necessary if you've performed steps 2 or 3 above.

    go install github.com/googleapis/gnostic
   

5. 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/petstore.json
   

6. 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
   

7. For a sample application, see apps/report.

    go install github.com/googleapis/gnostic/apps/report
    report petstore.pb
   

8. 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/go/gnostic_go_sample
    gnostic examples/petstore.json --go_sample_out=-
   

Copyright

Copyright 2017, Google Inc.

License

Released under the Apache 2.0 license.