README.md
1[](https://github.com/google/gnostic/actions)
2
3# ⨁ gnostic
4
5This repository contains a Go command line tool which converts JSON and YAML
6[OpenAPI](https://github.com/OAI/OpenAPI-Specification) descriptions to and
7from equivalent Protocol Buffer representations.
8
9[Protocol Buffers](https://developers.google.com/protocol-buffers/) provide a
10language-neutral, platform-neutral, extensible mechanism for serializing
11structured data. **gnostic**'s Protocol Buffer models for the OpenAPI
12Specification can be used to generate code that includes data structures with
13explicit fields for the elements of an OpenAPI description. This makes it
14possible for developers to work with OpenAPI descriptions in type-safe ways,
15which is particularly useful in strongly-typed languages like Go and
16[Dart](https://dart.dev/).
17
18**gnostic** reads OpenAPI descriptions into these generated data structures,
19reports errors, resolves internal dependencies, and writes the results in a
20binary form that can be used in any language that is supported by the Protocol
21Buffer tools. A plugin interface simplifies integration with API tools written
22in a variety of different languages, and when necessary, Protocol Buffer
23OpenAPI descriptions can be reexported as JSON or YAML.
24
25**gnostic** compilation code and OpenAPI Protocol Buffer models are
26automatically generated from an
27[OpenAPI JSON Schema](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json).
28Source code for the generator is in the [generate-gnostic](generate-gnostic)
29directory.
30
31## Disclaimer
32
33Feedback and contributions are welcome! Until there is a 1.0 release, please
34consider this prerelease software and work in progress. To ensure stable
35builds, we request that dependent projects always refer to tagged releases of
36**gnostic**.
37
38## Requirements
39
40**gnostic** can be run in any environment that supports [Go](http://golang.org)
41and the
42[Protocol Buffer Compiler](https://github.com/protocolbuffers/protobuf).
43
44## Installation and Getting Started
45
46The following instructions are for installing **gnostic** using
47[Go modules](https://blog.golang.org/using-go-modules), supported by Go 1.11
48and later.
49
501. Get this package by downloading it with `git clone`.
51
52 git clone https://github.com/googleapis/gnostic
53 cd gnostic
54
552. Verify that you have a local installation of `protoc`. You can get protoc
56 [here](https://github.com/protocolbuffers/protobuf).
57
583. Build **gnostic** with `make`. This uses
59 [go generate](https://blog.golang.org/generate) to build support code
60 including code generated by `protoc` and the Go protoc plugin, which is
61 automatically downloaded from
62 [github.com/golang/protobuf](https://github.com/golang/protobuf) by the
63 [COMPILE-PROTOS.sh](COMPILE-PROTOS.sh) script. This also builds all plugins
64 and associated tools in this repo.
65
664. Verify **gnostic** with `make test`. These tests are run by **gnostic**'s
67 continuous integration, so you should expect them to pass for all release
68 versions.
69
705. Run **gnostic**. This sample invocation creates a file in the current
71 directory named `petstore.pb` that contains a binary Protocol Buffer
72 description of a sample API.
73
74 gnostic --pb-out=. examples/v2.0/json/petstore.json
75
766. You can also compile files that you specify with a URL. Here's another way
77 to compile the previous example. This time we're creating `petstore.text`,
78 which contains a textual representation of the Protocol Buffer description.
79 This is mainly for use in testing and debugging.
80
81 gnostic --text-out=petstore.text https://raw.githubusercontent.com/googleapis/gnostic/master/examples/v2.0/json/petstore.json
82
837. For a sample application, see apps/report. This reads a binary Protocol
84 Buffer encoding created by **gnostic**.
85
86 go install ./apps/report ## automatically installed by the top-level Makefile
87 report petstore.pb
88
898. **gnostic** also supports plugins. **gnostic**'s plugin interface is
90 modeled on `protoc`'s
91 [plugin.proto](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/compiler/plugin.proto)
92 and is described in [plugins/plugin.proto](plugins/plugin.proto). Several
93 plugins are implemented in the `plugins` directory. Others, like
94 [gnostic-grpc](https://github.com/googleapis/gnostic-grpc) and
95 [gnostic-go-generator](https://github.com/googleapis/gnostic-go-generator),
96 are published in their own repositories. One such plugin is
97 [gnostic-vocabulary](plugins/gnostic-vocabulary), which produces a summary
98 of the word usage in an APIs interfaces. You can run `gnostic-vocabulary`
99 with the following:
100
101 gnostic examples/v2.0/json/petstore.json --vocabulary_out=.
102
103 This will produce files named `vocabulary.pb` and `vocabulary.json` in
104 `examples/v2.0/json`. For the format of `vocabulary.pb`, see
105 [metrics/vocabulary.proto](metrics/vocabulary.proto).
106
1079. [Optional] A large part of **gnostic** is automatically-generated by the
108 [generate-gnostic](generate-gnostic) tool. This uses JSON schemas to
109 generate Protocol Buffer language files that describe supported API
110 specification formats and Go-language files of code that will read JSON or
111 YAML API descriptions into the generated protocol buffer models.
112 Pre-generated versions of these files are checked into the
113 [openapiv2](openapiv2), [openapiv3](openapiv3), and [discovery](discovery)
114 directories. You can regenerate this code with the following:
115
116 go install ./generate-gnostic
117 generate-gnostic --v2
118 generate-gnostic --v3
119 generate-gnostic --discovery
120
121## Copyright
122
123Copyright 2017-2020, Google LLC.
124
125## License
126
127Released under the Apache 2.0 license.
128
){kind=link}