Required File Structure
│ └── mod
└── (anyname other than src)
├── protorepo *
brew install prototool
go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger go get -u github.com/golang/protobuf/protoc-gen-go
npm install ts-protoc-gen
Create a new service
- Create a new dir:
mkdir -p proto/new_service/v1beta1/
- (Optional) Create a config file if extra configs are needed:
prototool config init proto/new_service
- Create a protobuf template:
prototool create proto/new_service/v1beta1/new_service.proto
Write API definition Note:
all those definitions must follow the protobuf lint rules. Uber's lint rule v2 is recommended and set as the default lint rule since it is strict.
If extra REST interfaces are needed, follow the tutorial of grpc-gateway.
Lint your API:
prototool lint proto/new_service/v1beta1/new_service.proto
Note we are think of adding this lint process in our CI pipeline, any commit with lint error will be intolerant.
- Generate your API pb files:
prototool generate proto/new_service/v1beta1/new_service.proto
Generated pb files will be under
- Import file into your service codebase
Supported language pb files repo
Dependency management in golang is easy since golang has built-in git support for fetching 3rd-party libraries and this
only happens during development and build time. Simply import files like
should be fine.
python will be packaged as an egg file, simply import those files should be fine.
Java pb files will be packed into a jar file for easy import. Upload to the central maven repo if needed.
API is always changing. The basic idea is any API version number with suffix
beta# might introduces breaking
changes. Other APIs will not break, however.