gnostic

command module
v0.0.0-...-bbe6032 Latest Latest
Warning

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

Go to latest
Published: Apr 17, 2023 License: Apache-2.0 Imports: 3 Imported by: 0

README

Go Actions 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 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.

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.

google/gnostic-models contains a lightweight distribution of the protobuf models generated by this project. Where a low-dependency integration of just these models is needed, Go projects can import packages from gnostic-models instead of gnostic.

google/gnostic-grpc contains a gnostic plugin that can generate an annotated Protocol Buffer description of an API that, when transcode, produces an API that conforms to a specified OpenAPI document. To go from protobuf to OpenAPI, see the protoc-gen-openapi tool in this project.

google/gnostic-go-generator contains an experimental gnostic plugin that generates a Go client for an API described by a specified OpenAPI document.

Disclaimer

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.

Requirements

gnostic can be run in any environment that supports Go and the Protocol Buffer Compiler.

Installation and Getting Started

The following instructions are for installing gnostic using Go modules, supported by Go 1.11 and later.

  1. Get this package by downloading it with git clone.

    git clone https://github.com/flywish/gnostic
    cd gnostic
    
  2. Verify that you have a local installation of protoc. You can get protoc here.

  3. Build gnostic with make. This uses go generate to build support code including code generated by protoc and 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.

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

  5. 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
    
  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/google/gnostic/master/examples/v2.0/json/petstore.json
    
  7. 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
    
  8. 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 plugins directory. 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-vocabulary with the following:

        gnostic examples/v2.0/json/petstore.json --vocabulary_out=.
    

    This will produce files named vocabulary.pb and vocabulary.json in examples/v2.0/json. For the format of vocabulary.pb, see metrics/vocabulary.proto.

  9. [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.

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.

Directories

Path Synopsis
cmd
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.
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.
vocabulary
Package gnostic_vocabulary provides operation for Vocabulary structs
Package gnostic_vocabulary provides operation for Vocabulary structs
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.
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-complexity
gnostic-complexity is a plugin that generates a complexity summary of an API.
gnostic-complexity is a plugin that generates a complexity summary of an API.
gnostic-plugin-request
gnostic-plugin-request is a development tool that captures and optionally displays the contents of the gnostic plugin interface.
gnostic-plugin-request is a development tool that captures and optionally displays the contents of the gnostic plugin interface.
gnostic-process-plugin-response
gnostic-process-plugin-response is a development tool that processes the output of a gnostic plugin in the same way that it would be handled by gnostic itself.
gnostic-process-plugin-response is a development tool that processes the output of a gnostic plugin in the same way that it would be handled by gnostic itself.
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.
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