all: correct use of go_package

grpc-ecosystem · May 14, 2020 · 1b447b4 · 1b447b4
1 parent 699882b
commit 1b447b4
Show file tree

Hide file tree

Showing 44 changed files with 2,131 additions and 2,310 deletions.
diff --git a/Makefile b/Makefile
@@ -182,7 +182,7 @@ $(HELLOWORLD_SVCSRCS): $(GO_PLUGIN) $(HELLOWORLD)
 
 $(HELLOWORLD_GWSRCS):
 $(HELLOWORLD_GWSRCS): $(GATEWAY_PLUGIN) $(HELLOWORLD)
-	protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GATEWAY_PLUGIN) --grpc-gateway_out=logtostderr=true,allow_repeated_fields_in_body=true,$(PKGMAP)$(ADDITIONAL_GW_FLAGS):. $(HELLOWORLD)
+	protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GATEWAY_PLUGIN) --grpc-gateway_out=logtostderr=true,allow_repeated_fields_in_body=true,paths=source_relative,$(PKGMAP)$(ADDITIONAL_GW_FLAGS):. $(HELLOWORLD)
 
 
 $(ECHO_EXAMPLE_SRCS): $(ECHO_EXAMPLE_SPEC)

diff --git a/README.md b/README.md
@@ -85,15 +85,16 @@ Make sure that your `$GOBIN` is in your `$PATH`.
 
    `your_service.proto`:
    ```protobuf
-   syntax = "proto3";
-   package example;
-   message StringMessage {
-     string value = 1;
-   }
+    syntax = "proto3";
+    package your.service.v1;
+    option go_package = "github.com/yourorg/yourprotos/gen/go/your/service/v1";
+    message StringMessage {
+      string value = 1;
+    }
 
-   service YourService {
-     rpc Echo(StringMessage) returns (StringMessage) {}
-   }
+    service YourService {
+      rpc Echo(StringMessage) returns (StringMessage) {}
+    }
    ```
 
 2. Add a [`google.api.http`](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto#L46)
@@ -102,7 +103,8 @@ annotation to your .proto file
    `your_service.proto`:
    ```diff
     syntax = "proto3";
-    package example;
+    package your.service.v1;
+    option go_package = "github.com/yourorg/yourprotos/gen/go/your/service/v1";
    +
    +import "google/api/annotations.proto";
    +

diff --git a/docs/_docs/grpcapiconfiguration.md b/docs/_docs/grpcapiconfiguration.md
@@ -18,15 +18,16 @@ The following is equivalent to the basic [usage example](usage.html) but without
 
    your_service.proto:
    ```protobuf
-   syntax = "proto3";
-   package example;
-   message StringMessage {
-     string value = 1;
-   }
-   
-   service YourService {
-     rpc Echo(StringMessage) returns (StringMessage) {}
-   }
+    syntax = "proto3";
+    package your.service.v1;
+    option go_package = "github.com/yourorg/yourprotos/gen/go/your/service/v1";
+    message StringMessage {
+      string value = 1;
+    }
+    
+    service YourService {
+      rpc Echo(StringMessage) returns (StringMessage) {}
+    }
    ```
 
 2. Instead of annotating the .proto file in this step leave it untouched and create a `your_service.yaml` with the following content:
@@ -36,114 +37,29 @@ The following is equivalent to the basic [usage example](usage.html) but without
 
     http:
       rules:
-      - selector: example.YourService.Echo
+      - selector: your.service.v1.YourService.Echo
         post: /v1/example/echo
         body: "*"
     ```
     Use a [linter](http://www.yamllint.com/) to validate your YAML.
 
 3. Generate gRPC stub as before
    
-   ```sh
-   protoc -I/usr/local/include -I. \
-     -I$GOPATH/src \
-     -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
-     --go_out=plugins=grpc:. \
-     path/to/your_service.proto
-   ```
-
-   It will generate a stub file `path/to/your_service.pb.go`.
-4. Implement your service in gRPC as usual
-   1. (Optional) Generate gRPC stub in the language you want.
-
-     e.g.
-     ```sh
-     protoc -I/usr/local/include -I. \
-       -I$GOPATH/src \
-       -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
-       --ruby_out=. \
-       path/to/your/service_proto
-
-     protoc -I/usr/local/include -I. \
-       -I$GOPATH/src \
-       -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
-       --plugin=protoc-gen-grpc=grpc_ruby_plugin \
-       --grpc-ruby_out=. \
-       path/to/your/service.proto
-     ```
-   2. Add the googleapis-common-protos gem (or your language equivalent) as a dependency to your project.
-   3. Implement your service
-
-5. Generate reverse-proxy. Here we have to pass the path to the `your_service.yaml` in addition to the .proto file:
-   ```sh
-   protoc -I/usr/local/include -I. \
-     -I$GOPATH/src \
-     -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
-     --grpc-gateway_out=logtostderr=true,grpc_api_configuration=path/to/your_service.yaml:. \
-     path/to/your_service.proto
-   ```
-
-   This will generate a reverse proxy `path/to/your_service.pb.gw.go` that is identical to the one produced for the annotated proto.
-
-   Note: After generating the code for each of the stubs, in order to build the code, you will want to run ```go get .``` from the directory containing the stubs.
-
-6. Write an entrypoint 
-
-   Now you need to write an entrypoint of the proxy server. This step is the same whether the file is annotated or not.
-   ```go
-   package main
-
-   import (
-     "flag"
-     "net/http"
-   
-     "github.com/golang/glog"
-     "golang.org/x/net/context"
-     "github.com/grpc-ecosystem/grpc-gateway/runtime"
-     "google.golang.org/grpc"
-   	
-     gw "path/to/your_service_package"
-   )
-   
-   var (
-     echoEndpoint = flag.String("echo_endpoint", "localhost:9090", "endpoint of YourService")
-   )
-   
-   func run() error {
-     ctx := context.Background()
-     ctx, cancel := context.WithCancel(ctx)
-     defer cancel()
-   
-     mux := runtime.NewServeMux()
-     opts := []grpc.DialOption{grpc.WithInsecure()}
-     err := gw.RegisterYourServiceHandlerFromEndpoint(ctx, mux, *echoEndpoint, opts)
-     if err != nil {
-       return err
-     }
-   
-     return http.ListenAndServe(":8080", mux)
-   }
-   
-   func main() {
-     flag.Parse()
-     defer glog.Flush()
+    ```sh
+    protoc -I. --go_out=plugins=grpc,paths=source_relative:./gen/go/ your/service/v1/your_service.proto
+    ```
 
-     if err := run(); err != nil {
-       glog.Fatal(err)
-     }
-   }
-   ```
+  It will generate a stub file with path `./gen/go/your/service/v1/your_service.pb.go`.
 
-7. (Optional) Generate swagger definitions
+4. Implement your service in gRPC as usual
 
-Swagger generation in this step is equivalent to gateway generation. Again pass the path to the yaml file in addition to the proto:
+5. Generate the reverse-proxy. Here we have to pass the path to the `your_service.yaml` in addition to the .proto file:
 
    ```sh
-   protoc -I/usr/local/include -I. \
-     -I$GOPATH/src \
-     -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
-     --swagger_out=logtostderr=true,grpc_api_configuration=path/to/your_service.yaml:. \
-     path/to/your_service.proto
+   protoc -I. --grpc-gateway_out=logtostderr=true,paths=source_relative,grpc_api_configuration=path/to/your_service.yaml:./gen/go \
+     your/service/v1/your_service.proto
    ```
+
+   This will generate a reverse proxy `gen/go/your/service/v1/your_service.pb.gw.go` that is identical to the one produced for the annotated proto.
 
 All other steps work as before. If you want you can remove the googleapis include path in step 3 and 4 as the unannotated proto no longer requires them.