Oswee API

Important rules

• Every service in separate files
• File names with underscore file_name.proto

Uber guidelines

Google Guidelines

Tool to merge swagger files go-swagger/go-swagger

Prerequisites

Set up GOPATH in ~/.zshrc or ~/bashrc

source $HOME/.zshrc

export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export GOBIN=$GOPATH/bin
export PATH=$PATH:$GOROOT:$GOPATH:$GOBIN

In order to compile protobufs, /usr/local/include should be populated with protocolbuffers/protobuf. Copy include/google/protobuf directory from downloaded archive into /usr/local/include/google

Install grpc-gateway and swagger documentation generator plugins

go get -u github.com/golang/protobuf/protoc-gen-go
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

By default go get installs all packages in $GOPATH. If that is not specified then in $HOME/go.

Copy content of %GOPATH%/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis/google folder to /usr/local/include/google folder.

cp $GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis/google usr/local/include/google

Copy annotations.proto and openapiv2.proto files from %GOPATH%/src/github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger/options folder to /usr/local/include/protoc-gen-swagger/options folder.

It should look like this:

⚠️ DEPRECATED: All external annotations should be included in ./third_party/ directory.

/usr/local/include
├── google
│   ├── api
│   │   ├── annotations.proto
│   │   └── http.proto
│   ├── protobuf
│   │   ├── any.proto
│   │   ├── api.proto
│   │   ├── compiler
│   │   │   └── plugin.proto
│   │   ├── descriptor.proto
│   │   ├── duration.proto
│   │   ├── empty.proto
│   │   ├── field_mask.proto
│   │   ├── source_context.proto
│   │   ├── struct.proto
│   │   ├── timestamp.proto
│   │   ├── type.proto
│   │   └── wrappers.proto
│   └── rpc
│       ├── code.proto
│       ├── error_details.proto
│       └── status.proto
└── protoc-gen-swagger
    └── options
        ├── annotations.proto
        └── openapiv2.proto

UPDATE: In order to make this repository self-contained, i included vendored packages there and moved Oswee API in its own /oswee/* directory. This way, no matter where this repository will be hosted or used, all Google and Swagger protobufs will be included and i don't need to rely on /usr/local/include/*.

UPDATE2: It is not an good idea to move google/protobuf/* into repository as it is a part of protoc compiler and could lead to mismatch between compiler and used definitions.

Other

Check the version of protoc compiler

protoc --version

Update protoc compiler - StackOverflow

Resources

GitHub Issue about imports not found

Protoc Swagger example

gRPC endpoint testing

fullstorydev/grpcui

TypeScript

To generate TypeScript types i am using grpc-web plugin. At time of writing this, TypeScript support is experimental.

Lerna

Create personal access token

https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token

Create ~/.npmrc (or at project level) file with Auth token (DO NOT COMMIT AUTH TOKEN!!!)

https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages#authenticating-with-a-personal-access-token

Check the authentication

npm whoami --registry=https://npm.pkg.github.com