gnostic

command module
Version: v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 19, 2018 License: Apache-2.0 Imports: 19 Imported by: 0

README

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 2017, Google Inc.

License

Released under the Apache 2.0 license.

Documentation

Overview

Gnostic is a tool for building better REST APIs through knowledge.

Gnostic reads declarative descriptions of REST APIs that conform to the OpenAPI Specification, reports errors, resolves internal dependencies, and puts the results in a binary form that can be used in any language that is supported by the Protocol Buffer tools.

Gnostic models are validated and typed. This allows API tool developers to focus on their product and not worry about input validation and type checking.

Gnostic calls plugins that implement a variety of API implementation and support features including generation of client and server support code.

Source Files

Directories

Path Synopsis
Package openapi_v2 is a generated protocol buffer package.
Package openapi_v2 is a generated protocol buffer package.
Package openapi_v3 is a generated protocol buffer package.
Package openapi_v3 is a generated protocol buffer package.
schema-generator
schema-generator is a support tool that generates the OpenAPI v3 JSON schema.
schema-generator is a support tool that generates the OpenAPI v3 JSON schema.
apps
report
report is a demo application that displays information about an OpenAPI description.
report is a demo application that displays information about an OpenAPI description.
report-messages
Filter and display messages produced by gnostic invocations.
Filter and display messages produced by gnostic invocations.
Package compiler provides support functions to generated compiler code.
Package compiler provides support functions to generated compiler code.
Package discovery_v1 is a generated protocol buffer package.
Package discovery_v1 is a generated protocol buffer package.
Package openapiextension_v1 is a generated protocol buffer package.
Package openapiextension_v1 is a generated protocol buffer package.
generator generates Protocol Buffer models and support code from JSON Schemas.
generator generates Protocol Buffer models and support code from JSON Schemas.
Package jsonschema supports the reading, writing, and manipulation of JSON Schemas.
Package jsonschema supports the reading, writing, and manipulation of JSON Schemas.
linters
go/gnostic-lint-descriptions
gnostic_lint is a tool for analyzing OpenAPI descriptions.
gnostic_lint is a tool for analyzing OpenAPI descriptions.
go/gnostic-lint-paths
gnostic-lint-paths is a tool for analyzing paths in OpenAPI descriptions.
gnostic-lint-paths is a tool for analyzing paths in OpenAPI descriptions.
Package gnostic_plugin_v1 is a generated protocol buffer package.
Package gnostic_plugin_v1 is a generated protocol buffer package.
gnostic-analyze
gnostic_analyze is a tool for analyzing OpenAPI descriptions.
gnostic_analyze is a tool for analyzing OpenAPI descriptions.
gnostic-analyze/summarize
summarize is a tool for summarizing the results of gnostic_analyze runs.
summarize is a tool for summarizing the results of gnostic_analyze runs.
gnostic-go-generator
gnostic_go_generator is a sample Gnostic plugin that generates Go code that supports an API.
gnostic_go_generator is a sample Gnostic plugin that generates Go code that supports an API.
gnostic-go-generator/examples/v2.0/bookstore/bookstore
Package bookstore exists to allow this repo to work with recursive go get.
Package bookstore exists to allow this repo to work with recursive go get.
gnostic-go-generator/examples/v2.0/sample/sample
Package sample exists to allow this repo to work with recursive go get.
Package sample exists to allow this repo to work with recursive go get.
gnostic-go-generator/examples/v2.0/xkcd/xkcd
Package xkcd exists to allow this repo to work with recursive go get.
Package xkcd exists to allow this repo to work with recursive go get.
gnostic-go-generator/examples/v3.0/bookstore/bookstore
Package bookstore exists to allow this repo to work with recursive go get.
Package bookstore exists to allow this repo to work with recursive go get.
gnostic-go-generator/examples/v3.0/urlshortener/urlshortener
Package urlshortener exists to allow this repo to work with recursive go get.
Package urlshortener exists to allow this repo to work with recursive go get.
gnostic-summary
gnostic_go_generator is a sample Gnostic plugin that generates Go code that supports an API.
gnostic_go_generator is a sample Gnostic plugin that generates Go code that supports an API.
Package printer provides support for writing generated code.
Package printer provides support for writing generated code.
Package surface_v1 is a generated protocol buffer package.
Package surface_v1 is a generated protocol buffer package.
tools
format-schema
format-schema canonically formats a JSON schema.
format-schema canonically formats a JSON schema.
j2y2j
j2y2j converts JSON to YAML and YAML to JSON.
j2y2j converts JSON to YAML and YAML to JSON.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL