Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zchee/protoc-gen-openapi
protoc-gen-openapi is a plugin for the Google protocol buffer compiler to generate openAPI V3 spec for any given input protobuf.
https://github.com/zchee/protoc-gen-openapi
openapi openapi3 protobuf protoc protoc-plugin
Last synced: 3 months ago
JSON representation
protoc-gen-openapi is a plugin for the Google protocol buffer compiler to generate openAPI V3 spec for any given input protobuf.
- Host: GitHub
- URL: https://github.com/zchee/protoc-gen-openapi
- Owner: zchee
- License: apache-2.0
- Created: 2019-09-07T17:43:22.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2019-09-07T17:43:31.000Z (over 5 years ago)
- Last Synced: 2024-06-21T06:33:14.127Z (7 months ago)
- Topics: openapi, openapi3, protobuf, protoc, protoc-plugin
- Language: Go
- Homepage: https://godoc.org/github.com/zchee/protoc-gen-openapi
- Size: 265 KB
- Stars: 6
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# protoc-gen-openapi
This package copy from [istio.io/tools/openapi/protoc-gen-openapi@593a41c76c5c](https://github.com/istio/tools/tree/593a41c76c5c84a4cd51a4ab0c345630c5ed30ba/openapi/protoc-gen-openapi).
## What's this for?
`protoc-gen-openapi` is a plugin for the Google protocol buffer compiler to generate
openAPI V3 spec for any given input protobuf. It runs as a `protoc-gen-` binary that the
protobuf compiler infers from the `openapi_out` flag.
## Build `protoc-gen-openapi`
`protoc-gen-openapi` is written in Go, so ensure that is installed on your system. You
can follow the instructions on the [golang website](https://golang.org/doc/install) or
on Debian or Ubuntu, you can install it from the package manager:
```bash
sudo apt-get install -y golang
```
To build, first ensure you have the protocol compiler (protoc):
```bash
go get github.com/golang/protobuf/proto
```
To build, run the following command from this project directory:
```bash
go build
```
Then ensure the resulting `protoc-gen-openapi` binary is in your `PATH`. A recommended location
is `$HOME/bin`:
```bash
cp protoc-gen-openapi $HOME/bin
```
Since the following is often in your `$HOME/.bashrc` file:
```bash
export PATH=$HOME/bin:$PATH
```
## Using protoc-gen-openapi
---
**TIP**
The -I option in protoc is useful when you need to specify proto paths for imports.
---
Then to generate the OpenAPI spec of the protobuf defined by file.proto, run
```bash
protoc --openapi_out=output_directory input_directory/file.proto
```
With that input, the output will be written to
output_directory/file.json
Other supported options are:
* `per_file`
* when set to `true`, the output is per proto file instead of per package.
* `single_file`
* when set to `true`, the output is a single file of all the input protos specified.
* `use_ref`
* when set to `true`, the output uses the `$ref` field in OpenAPI spec to reference other schemas.
* `yaml`
* when set to `true`, the output is in yaml file.