Skip to content

Commit f0ca341

Browse files
Improve generation README docs
Use paths=source_relative in README Probably the most useful feature of protoc-gen-go, it's also supported by the gateway generator, so lets add it to the example. Update generation guide Instead of using the GOPATH to import the third_party folder, recommend the use of of a protobuf source tree with the dependencies copied in.
1 parent 9d6483f commit f0ca341

File tree

1 file changed

+23
-37
lines changed

1 file changed

+23
-37
lines changed

README.md

Lines changed: 23 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -125,66 +125,57 @@ annotation to your .proto file
125125

126126
3. Generate gRPC stub
127127

128-
The following generates gRPC code for Golang based on `path/to/your_service.proto`:
129-
```sh
130-
protoc -I/usr/local/include -I. \
131-
-I$GOPATH/src \
132-
-I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
133-
--go_out=plugins=grpc:. \
134-
path/to/your_service.proto
135-
```
128+
You will need to provide the required third party protobuf files to the `protoc` compiler.
129+
They are included in this repo under the `third_party/googleapis` folder, and we recommend copying
130+
them into your `protoc` generation file structure. If you've structured your protofiles according
131+
to something like [the Buf style guide](https://buf.build/docs/style-guide#files-and-packages),
132+
you could copy the files into a top-level `./google` folder.
133+
134+
Here is an example of what a `protoc` command might look like:
136135

137-
It will generate a stub file `path/to/your_service.pb.go`.
136+
```sh
137+
protoc -I. --go_out=plugins=grpc,paths=source_relative:./gen/go/ your/service/v1/your_service.proto
138+
```
139+
140+
It will generate a stub file with path `./gen/go/your/service/v1/your_service.pb.go`.
138141

139142
4. Implement your service in gRPC as usual
140143

141144
1. (Optional) Generate gRPC stub in the [other programming languages](https://grpc.io/docs/).
142145

143-
For example, the following generates gRPC code for Ruby based on `path/to/your_service.proto`:
146+
For example, the following generates gRPC code for Ruby based on `your/service/v1/your_service.proto`:
144147
```sh
145-
protoc -I/usr/local/include -I. \
146-
-I$GOPATH/src \
147-
-I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
148-
--ruby_out=. \
149-
path/to/your_service.proto
150-
151-
protoc -I/usr/local/include -I. \
152-
-I$GOPATH/src \
153-
-I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
154-
--plugin=protoc-gen-grpc=grpc_ruby_plugin \
155-
--grpc-ruby_out=. \
156-
path/to/your_service.proto
148+
protoc -I. --ruby_out=./gen/ruby your/service/v1/your_service.proto
149+
150+
protoc -I. --grpc-ruby_out=./gen/ruby your/service/v1/your_service.proto
157151
```
158152
2. Add the googleapis-common-protos gem (or your language equivalent) as a dependency to your project.
159153
3. Implement your gRPC service stubs
160154

161155
5. Generate reverse-proxy using `protoc-gen-grpc-gateway`
162156

163157
```sh
164-
protoc -I/usr/local/include -I. \
165-
-I$GOPATH/src \
166-
-I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
167-
--grpc-gateway_out=logtostderr=true:. \
168-
path/to/your_service.proto
158+
protoc -I. --grpc-gateway_out=logtostderr=true,paths=source_relative:./gen/go \
159+
your/service/v1/your_service.proto
169160
```
170161

171-
It will generate a reverse proxy `path/to/your_service.pb.gw.go`.
162+
It will generate a reverse proxy `gen/go/your/service/v1/your_service.pb.gw.go`.
172163

173164
6. Write an entrypoint for the HTTP reverse-proxy server
174165

175166
```go
176167
package main
177168
178169
import (
179-
"context" // Use "golang.org/x/net/context" for Golang version <= 1.6
170+
"context"
180171
"flag"
181172
"net/http"
182173
183174
"github.com/golang/glog"
184175
"github.com/grpc-ecosystem/grpc-gateway/runtime"
185176
"google.golang.org/grpc"
186177
187-
gw "path/to/your_service_package" // Update
178+
gw "github.com/yourorg/yourrepo/proto/gen/go/your/service/v1/your_service" // Update
188179
)
189180
190181
var (
@@ -224,11 +215,7 @@ annotation to your .proto file
224215
7. (Optional) Generate swagger definitions using `protoc-gen-swagger`
225216
226217
```sh
227-
protoc -I/usr/local/include -I. \
228-
-I$GOPATH/src \
229-
-I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
230-
--swagger_out=logtostderr=true:. \
231-
path/to/your_service.proto
218+
protoc -I. --swagger_out=logtostderr=true:./gen/swagger your/service/v1/your_service.proto
232219
```
233220
234221
## Video intro
@@ -253,8 +240,7 @@ example:
253240
254241
`protoc-gen-grpc-gateway` supports custom mapping from Protobuf `import` to
255242
Golang import paths. They are compatible to
256-
[the parameters with same names in `protoc-gen-go`](https://github.com/golang/protobuf#parameters)
257-
(except `source_relative`).
243+
[the parameters with same names in `protoc-gen-go`](https://github.com/golang/protobuf#parameters).
258244
259245
In addition we also support the `request_context` parameter in order to use the
260246
`http.Request`'s Context (only for Go 1.7 and above). This parameter can be

0 commit comments

Comments
 (0)