https://github.com/pseudomuto/protoc-gen-twagger
A Protobuf plugin that generates Swagger docs for Twirp Services
https://github.com/pseudomuto/protoc-gen-twagger
documentation protobuf swagger twirp
Last synced: about 1 month ago
JSON representation
A Protobuf plugin that generates Swagger docs for Twirp Services
- Host: GitHub
- URL: https://github.com/pseudomuto/protoc-gen-twagger
- Owner: pseudomuto
- License: mit
- Created: 2018-02-04T05:50:23.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-02-26T14:16:07.000Z (over 7 years ago)
- Last Synced: 2025-03-27T14:55:06.936Z (6 months ago)
- Topics: documentation, protobuf, swagger, twirp
- Language: Go
- Homepage:
- Size: 249 KB
- Stars: 10
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# protoc-gen-twagger
[![Travis Build Status][travis-svg]][travis-ci]
[![codecov][codecov-svg]][codecov-url]
[![GoDoc][godoc-svg]][godoc-url]
[![Go Report Card][goreport-svg]][goreport-url]
A protobuf plugin that generates [Swagger] docs for your [Twirp] services.
Lots of assumptions being made at the moment...use with caution.
For a demo, clone the repo and run `make setup swagger`. Then open your browser to http://localhost:8080 and browse around.
## Running the Plugin
You'll need to install the binary.
`go get -u github.com/pseudomuto/protoc-gen-twagger/cmd/protoc-gen-twagger`
Even better, if you use a tool like [retool](https://github.com/twitchtv/retool) you can get a specific version. For
example:
`retool add github.com/pseudomuto/protoc-gen-twagger/cmd/protoc-gen-twagger `
Once installed you can invoke it with `protoc` like so:
`protoc -I. -I$(GOPATH)src --twagger_out=. input_proto1.proto input_proto2.proto`
This will generate `swagger.json` in the current directory.
**Using Docker**
Alternatively you can run this with docker. There's a public image `pseudomuto/protoc-gen-twagger` which can be used to
run the plugin.
```shell
docker run --rm \
-v $(pwd)/protos:/in:ro \
-v $(pwd):/out:rw \
pseudomuto/protoc-gen-twagger input_proto1.proto input_proto2.proto
```
Input paths are relative from `/in` inside the container. Take a look at the `run-docker` make task for a working
example.
[Swagger]: https://swagger.io/
[Twirp]: https://github.com/twitchtv/twirp
[travis-svg]:
https://travis-ci.org/pseudomuto/protoc-gen-twagger.svg?branch=master
"Travis CI build status SVG"
[travis-ci]:
https://travis-ci.org/pseudomuto/protoc-gen-twagger
"protoc-gen-twagger at Travis CI"
[codecov-svg]: https://codecov.io/gh/pseudomuto/protoc-gen-twagger/branch/master/graph/badge.svg
[codecov-url]: https://codecov.io/gh/pseudomuto/protoc-gen-twagger
[godoc-svg]: https://godoc.org/github.com/pseudomuto/protoc-gen-twagger?status.svg
[godoc-url]: https://godoc.org/github.com/pseudomuto/protoc-gen-twagger
[goreport-svg]: https://goreportcard.com/badge/github.com/pseudomuto/protoc-gen-twagger
[goreport-url]: https://goreportcard.com/report/github.com/pseudomuto/protoc-gen-twagger