Adapt usage instructions to use protoc-gen-go-grpc (#1755)

* Adapt usage instructions to use protoc-gen-go-grpc

This reflect recent changes in https://grpc.io/docs/languages/go/quickstart/
to use new protoc-gen-go-grpc.

Also remove a duplicated paragraph.

* Readme: use new protoc-gen-go

Replace github.com/golang/protobuf/protoc-gen-go by
google.golang.org/protobuf/cmd/protoc-gen-go

* Update other instructions to use protoc-gen-go-grpc

* Use --x-opt in instructions

* Update docs/_docs/usegotemplates.md

Co-authored-by: Johan Brandhorst-Satzkorn <[email protected]>

* Use go get instead of go get -u

Co-authored-by: Johan Brandhorst-Satzkorn <[email protected]>

Author: olivierlemasle

.github/ISSUE_TEMPLATE.md

@@ -4,13 +4,13 @@
 - [ ] Update your protoc to the [latest version](https://github.com/google/protobuf/releases).
 - [ ] Update your copy of the `grpc-gateway` library to the latest version from github:
   ```sh
-  go get -u github.com/grpc-ecosystem/grpc-gateway
+  go get github.com/grpc-ecosystem/grpc-gateway/v2@latest
   ```
 - [ ] Delete the `protoc-gen-grpc-gateway` and `protoc-gen-openapiv2` binary from your `PATH`,
   and reinstall the latest versions:
   ```sh
-  go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
-  go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv2
+  go get github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway
+  go get github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2
   ```
 
 ## I still have a problem!

README.md

@@ -62,7 +62,8 @@ package tools
 import (
     _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway"
     _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2"
-    _ "github.com/golang/protobuf/protoc-gen-go"
+    _ "google.golang.org/grpc/cmd/protoc-gen-go-grpc"
+    _ "google.golang.org/protobuf/cmd/protoc-gen-go"
 )
 ```
 
@@ -72,14 +73,16 @@ Run `go mod tidy` to resolve the versions. Install by running
 $ go install \
     github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway \
     github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2 \
-    github.com/golang/protobuf/protoc-gen-go
+    google.golang.org/protobuf/cmd/protoc-gen-go \
+    google.golang.org/grpc/cmd/protoc-gen-go-grpc
 ```
 
-This will place three binaries in your `$GOBIN`;
+This will place four binaries in your `$GOBIN`;
 
 * `protoc-gen-grpc-gateway`
 * `protoc-gen-openapiv2`
 * `protoc-gen-go`
+* `protoc-gen-go-grpc`
 
 Make sure that your `$GOBIN` is in your `$PATH`.
 
@@ -108,7 +111,10 @@ Make sure that your `$GOBIN` is in your `$PATH`.
     Here's an example of what a `protoc` command might look like to generate Go stubs:
 
     ```sh
-    protoc -I . --go_out ./gen/go/ --go_opt plugins=grpc --go_opt paths=source_relative your/service/v1/your_service.proto
+    protoc -I . \
+       --go_out ./gen/go/ --go_opt paths=source_relative \
+       --go-grpc_out ./gen/go/ --go-grpc_opt paths=source_relative \
+       your/service/v1/your_service.proto
     ```
 
 3. Implement your service in gRPC as usual
@@ -178,11 +184,6 @@ Make sure that your `$GOBIN` is in your `$PATH`.
    +  }
     }
    ```
-   >You will need to provide the required third party protobuf files to the `protoc` compiler.
-   >They are included in this repo under the `third_party/googleapis` folder, and we recommend copying
-   >them into your `protoc` generation file structure. If you've structured your proto files according
-   >to something like [the Buf style guide](https://buf.build/docs/style-guide#files-and-packages),
-   >you could copy the files into a top-level `./google` folder.
 
    >You will need to provide the required third party protobuf files to the `protoc` compiler.
    >They are included in this repo under the `third_party/googleapis` folder, and we recommend copying

docs/_docs/cygwin.md

@@ -35,17 +35,18 @@ From an elevated cmd.exe prompt set the GOPATH variable in Windows and add the `
 
 Then `go get -u -v` the following packages:
 
-    go get -u -v github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
-    go get -u -v github.com/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv2
-    go get -u -v github.com/golang/protobuf/protoc-gen-go
+    go get -u -v github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway
+    go get -u -v github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2
+    go get -u -v google.golang.org/protobuf/cmd/protoc-gen-go
+    go get -u -v google.golang.org/grpc/cmd/protoc-gen-go-grpc
 
 This will probably fail with a similar output to this:
 
     github.com/grpc-ecosystem/grpc-gateway (download)
     # cd .; git clone https://github.com/grpc-ecosystem/grpc-gateway C:\path\to\your\cygwin\home\user\go\src\github.com\grpc-ecosystem\grpc-gateway
     Cloning into 'C:\path\to\your\cygwin\home\user\go\src\github.com\grpc-ecosystem\grpc-gateway'...
     fatal: Invalid path '/home/user/go/C:\path\to\your\cygwin\home\user\go\src\github.com\grpc-ecosystem\grpc-gateway': No such file or directory
-    package github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway: exit status 128
+    package github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway: exit status 128
 
 To fix this you need to run the `go get -u -v` commands and look for all lines starting with `# cd .;`.
 Copy and paste these lines into your shell and change the clone destination directories.
@@ -63,7 +64,7 @@ Follow the [instructions](https://github.com/grpc-ecosystem/grpc-gateway#usage)
 
 Adjust steps 3, 5 and 7 like this. protoc expects native Windows paths.
 
-    protoc -I. -I$(cygpath -w /usr/local/include) -I${GOPATH}/src -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --go_out=plugins=grpc:. ./path/to/your_service.proto
+    protoc -I. -I$(cygpath -w /usr/local/include) -I${GOPATH}/src -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --go_out=. --go-grpc_out=. ./path/to/your_service.proto
     protoc -I. -I$(cygpath -w /usr/local/include) -I${GOPATH}/src -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --grpc-gateway_out=logtostderr=true:. ./path/to/your_service.proto
     protoc -I. -I$(cygpath -w /usr/local/include) -I${GOPATH}/src -I${GOPATH}/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --openapiv2_out=logtostderr=true:. ./path/to/your_service.proto
 

docs/_docs/grpcapiconfiguration.md

@@ -21,7 +21,7 @@ This is similar to how [Cloud Endpoints behaves](https://cloud.google.com/endpoi
 * URI path is built from the service's name and method: `/<fully qualified service name>/<method name>` (e.g.: `/my.package.EchoService/Echo`)
 * HTTP body is the serialized protobuf message.
 
-NOTE: the same option is also supported by the `gen-swagger` plugin.
+NOTE: the same option is also supported by the `gen-openapiv2` plugin.
 
 ## Using an external configuration file
 Google Cloud Platform offers a way to do this for services hosted with them called ["gRPC API Configuration"](https://cloud.google.com/endpoints/docs/grpc/grpc-service-config). It can be used to define the behavior of a gRPC API service without modifications to the service itself in the form of [YAML](https://en.wikipedia.org/wiki/YAML) configuration files.
@@ -66,7 +66,12 @@ The following is equivalent to the basic [usage example](usage.html) but without
 3. Generate gRPC stub as before
 
     ```sh
-    protoc -I. --go_out=plugins=grpc,paths=source_relative:./gen/go/ your/service/v1/your_service.proto
+    protoc -I . \
+      --go_out ./gen/go/ \
+      --go_opt paths=source_relative \
+      --go-grpc_out ./gen/go/ \
+      --go-grpc_opt paths=source_relative \
+      your/service/v1/your_service.proto
     ```
 
   It will generate a stub file with path `./gen/go/your/service/v1/your_service.pb.go`.
@@ -77,7 +82,11 @@ The following is equivalent to the basic [usage example](usage.html) but without
     the `your_service.yaml` in addition to the .proto file:
 
     ```sh
-    protoc -I. --grpc-gateway_out=logtostderr=true,paths=source_relative,grpc_api_configuration=path/to/your_service.yaml:./gen/go \
+    protoc -I . \
+      --grpc-gateway_out ./gen/go \
+      --grpc-gateway_opt logtostderr=true \
+      --grpc-gateway_opt paths=source_relative \
+      --grpc-gateway_opt grpc_api_configuration=path/to/your_service.yaml \
       your/service/v1/your_service.proto
     ```
 
@@ -86,24 +95,25 @@ The following is equivalent to the basic [usage example](usage.html) but without
 6. Generate the optional your_service.swagger.json
 
     ```sh
-    protoc -I . --swagger_out ./gen/go \
-      --swagger_opt grpc_api_configuration=path/to/your_service.yaml \
+    protoc -I . --openapiv2_out ./gen/go \
+      --openapiv2_opt grpc_api_configuration=path/to/your_service.yaml \
       your/service/v1/your_service.proto
     ```
 
     or using an OpenAPI configuration file
 
     ```sh
-    protoc -I . --swagger_out ./gen/go \
-      --swagger_opt grpc_api_configuration=path/to/your_service.yaml \
-      --swagger_opt openapi_configuration=path/to/your_service_swagger.yaml \
+    protoc -I . --openapiv2_out ./gen/go \
+      --openapiv2_opt grpc_api_configuration=path/to/your_service.yaml \
+      --openapiv2_opt openapi_configuration=path/to/your_service_swagger.yaml \
       your/service/v1/your_service.proto
     ```
 
     For an example of an OpenAPI configuration file, see [unannotated_echo_service.swagger.yaml](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/unannotated_echo_service.swagger.yaml), which adds OpenAPI options to [unannotated_echo_service.proto](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/unannotated_echo_service.proto).
 
     ```sh
-    protoc -I. --swagger_out=grpc_api_configuration=path/to/your_service.yaml:./gen/go \
+    protoc -I . --openapiv2_out ./gen/go \
+      --openapiv2_opt grpc_api_configuration=path/to/your_service.yaml \
       your/service/v1/your_service.proto
     ```
     

docs/_docs/usegotemplates.md

@@ -15,8 +15,13 @@ as:
 ## How to use it
 
 By default this function is turned off, so if you want to use it you
-have to set the `use_go_templates` flag to true inside of the
-`openapiv2_out` flag.
+have to add the `use_go_templates` option:
+
+```shell
+--openapiv2_out . --openapiv2_opt use_go_templates=true
+```
+
+or:
 
 ```shell
 --openapiv2_out=use_go_templates=true:.
@@ -28,9 +33,11 @@ Example of a bash script with the `use_go_templates` flag set to true:
 
 ```shell
 $ protoc -I. \
-    --go_out=plugins=grpc:. \
-    --grpc-gateway_out=logtostderr=true:. \
-    --openapiv2_out=logtostderr=true,use_go_templates=true:. \
+    --go_out . --go-grpc_out . \
+    --grpc-gateway_out . --grpc-gateway_opt logtostderr=true \
+    --openapiv2_out . \
+    --openapiv2_opt logtostderr=true \
+    --openapiv2_opt use_go_templates=true \
     path/to/my/proto/v1/myproto.proto 
 ```