diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 23f0f71a680..bc2066336a8 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.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! diff --git a/README.md b/README.md index 05d46f49e6f..87f1ea732ef 100644 --- a/README.md +++ b/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 diff --git a/docs/_docs/cygwin.md b/docs/_docs/cygwin.md index a089f5413be..3963698c8c1 100644 --- a/docs/_docs/cygwin.md +++ b/docs/_docs/cygwin.md @@ -35,9 +35,10 @@ 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: @@ -45,7 +46,7 @@ This will probably fail with a similar output to this: # 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 diff --git a/docs/_docs/grpcapiconfiguration.md b/docs/_docs/grpcapiconfiguration.md index 649073b3344..fbb51920869 100644 --- a/docs/_docs/grpcapiconfiguration.md +++ b/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: `//` (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 ``` diff --git a/docs/_docs/usegotemplates.md b/docs/_docs/usegotemplates.md index f984879021d..2ed630201be 100644 --- a/docs/_docs/usegotemplates.md +++ b/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 ```