Support generating unbound methods

Cherry picks 141dba3
from master.

Co-authored-by: Philippe Laflamme <[email protected]>

Author: johanbrandhorst

Makefile

@@ -41,7 +41,6 @@ GATEWAY_PLUGIN_FLAGS?=
 OPENAPI_PLUGIN_FLAGS?=
 
 GOOGLEAPIS_DIR=third_party/googleapis
-OUTPUT_DIR=_output
 
 OPENAPIV2_PROTO=protoc-gen-openapiv2/options/openapiv2.proto protoc-gen-openapiv2/options/annotations.proto
 OPENAPIV2_GO=$(OPENAPIV2_PROTO:.proto=.pb.go)
@@ -75,6 +74,7 @@ EXAMPLES=examples/internal/proto/examplepb/echo_service.proto \
 	 examples/internal/proto/examplepb/response_body_service.proto
 
 STANDALONE_EXAMPLES=examples/internal/proto/examplepb/unannotated_echo_service.proto
+GENERATE_UNBOUND_METHODS_EXAMPLE=examples/internal/proto/examplepb/generate_unbound_methods.proto
 
 HELLOWORLD=examples/internal/helloworld/helloworld.proto
 
@@ -85,6 +85,10 @@ EXAMPLE_OPENAPIMERGESRCS=examples/internal/proto/examplepb/openapi_merge.swagger
 EXAMPLE_DEPS=examples/internal/proto/pathenum/path_enum.proto examples/internal/proto/sub/message.proto examples/internal/proto/sub2/message.proto
 EXAMPLE_DEPSRCS=$(EXAMPLE_DEPS:.proto=.pb.go)
 
+GENERATE_UNBOUND_METHODS_EXAMPLE_OPENAPISRCS=$(GENERATE_UNBOUND_METHODS_EXAMPLE:.proto=.swagger.json)
+GENERATE_UNBOUND_METHODS_EXAMPLE_SVCSRCS=$(GENERATE_UNBOUND_METHODS_EXAMPLE:.proto=.pb.go)
+GENERATE_UNBOUND_METHODS_EXAMPLE_GWSRCS=$(GENERATE_UNBOUND_METHODS_EXAMPLE:.proto=.pb.gw.go)
+
 HELLOWORLD_SVCSRCS=$(HELLOWORLD:.proto=.pb.go)
 HELLOWORLD_GWSRCS=$(HELLOWORLD:.proto=.pb.gw.go)
 
@@ -140,8 +144,14 @@ RESPONSE_BODY_EXAMPLE_SRCS=$(EXAMPLE_CLIENT_DIR)/responsebody/client.go \
 		 $(EXAMPLE_CLIENT_DIR)/responsebody/model_examplepb_response_body_out_response.go \
 		 $(EXAMPLE_CLIENT_DIR)/responsebody/model_response_response_type.go \
 		 $(EXAMPLE_CLIENT_DIR)/responsebody/api_response_body_service.go
-
-EXAMPLE_CLIENT_SRCS=$(ECHO_EXAMPLE_SRCS) $(ABE_EXAMPLE_SRCS) $(UNANNOTATED_ECHO_EXAMPLE_SRCS) $(RESPONSE_BODY_EXAMPLE_SRCS)
+GENERATE_UNBOUND_METHODS_EXAMPLE_SPEC=examples/internal/proto/examplepb/generate_unbound_methods.swagger.json
+GENERATE_UNBOUND_METHODS_EXAMPLE_SRCS=$(EXAMPLE_CLIENT_DIR)/generateunboundmethods/client.go \
+		 $(EXAMPLE_CLIENT_DIR)/generateunboundmethods/response.go \
+		 $(EXAMPLE_CLIENT_DIR)/generateunboundmethods/configuration.go \
+		 $(EXAMPLE_CLIENT_DIR)/generateunboundmethods/model_examplepb_generate_unbound_methods_simple_message.go \
+		 $(EXAMPLE_CLIENT_DIR)/generateunboundmethods/api_generate_unbound_methods.go
+
+EXAMPLE_CLIENT_SRCS=$(ECHO_EXAMPLE_SRCS) $(ABE_EXAMPLE_SRCS) $(UNANNOTATED_ECHO_EXAMPLE_SRCS) $(RESPONSE_BODY_EXAMPLE_SRCS) $(GENERATE_UNBOUND_METHODS_EXAMPLE_SRCS)
 SWAGGER_CODEGEN=swagger-codegen
 
 PROTOC_INC_PATH=$(dir $(shell which protoc))/../include
@@ -189,6 +199,13 @@ $(EXAMPLE_OPENAPISRCS): $(OPENAPI_PLUGIN) $(OPENAPI_EXAMPLES)
 $(EXAMPLE_OPENAPIMERGESRCS): $(OPENAPI_PLUGIN) $(OPENAPIMERGE_EXAMPLES)
 	protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(OPENAPI_PLUGIN) --openapiv2_out=logtostderr=true,allow_repeated_fields_in_body=true,use_go_templates=true,allow_merge=true,merge_file_name=$(EXAMPLE_OPENAPIMERGESRCS:.swagger.json=):. $(OPENAPIMERGE_EXAMPLES)
 
+$(GENERATE_UNBOUND_METHODS_EXAMPLE_GWSRCS): $(GATEWAY_PLUGIN) $(GENERATE_UNBOUND_METHODS_EXAMPLE)
+	protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GATEWAY_PLUGIN) --grpc-gateway_out=logtostderr=true,paths=source_relative,allow_repeated_fields_in_body=true,generate_unbound_methods=true$(ADDITIONAL_GW_FLAGS):. $(GENERATE_UNBOUND_METHODS_EXAMPLE)
+$(GENERATE_UNBOUND_METHODS_EXAMPLE_SVCSRCS): $(GO_PLUGIN) $(GENERATE_UNBOUND_METHODS_EXAMPLE)
+	protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GO_PLUGIN) --plugin=$(GO_GRPC_PLUGIN) --go_out=paths=source_relative:. --go-grpc_out=paths=source_relative:. $(GENERATE_UNBOUND_METHODS_EXAMPLE)
+$(GENERATE_UNBOUND_METHODS_EXAMPLE_OPENAPISRCS): $(OPENAPI_PLUGIN) $(GENERATE_UNBOUND_METHODS_EXAMPLE)
+	protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(OPENAPI_PLUGIN) --openapiv2_out=logtostderr=true,allow_repeated_fields_in_body=true,use_go_templates=true,generate_unbound_methods=true:. $(GENERATE_UNBOUND_METHODS_EXAMPLE)
+
 $(HELLOWORLD_SVCSRCS): $(GO_PLUGIN) $(GO_GRPC_PLUGIN) $(HELLOWORLD)
 	protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GO_PLUGIN) --plugin=$(GO_GRPC_PLUGIN) --go_out=paths=source_relative:. --go-grpc_out=paths=source_relative:. $(HELLOWORLD)
 
@@ -217,8 +234,13 @@ $(RESPONSE_BODY_EXAMPLE_SRCS): $(RESPONSE_BODY_EXAMPLE_SPEC)
 		-l go -o examples/internal/clients/responsebody --additional-properties packageName=responsebody
 	@rm -f $(EXAMPLE_CLIENT_DIR)/responsebody/README.md \
 		$(EXAMPLE_CLIENT_DIR)/responsebody/git_push.sh
+$(GENERATE_UNBOUND_METHODS_EXAMPLE_SRCS): $(GENERATE_UNBOUND_METHODS_EXAMPLE_SPEC)
+	$(SWAGGER_CODEGEN) generate -i $(GENERATE_UNBOUND_METHODS_EXAMPLE_SPEC) \
+	    -l go -o examples/internal/clients/generateunboundmethods --additional-properties packageName=generateunboundmethods
+	@rm -f $(EXAMPLE_CLIENT_DIR)/generateunboundmethods/README.md \
+		$(EXAMPLE_CLIENT_DIR)/generateunboundmethods/git_push.sh
 
-examples: $(EXAMPLE_DEPSRCS) $(EXAMPLE_SVCSRCS) $(EXAMPLE_GWSRCS) $(EXAMPLE_OPENAPISRCS) $(EXAMPLE_OPENAPIMERGESRCS) $(EXAMPLE_CLIENT_SRCS) $(HELLOWORLD_SVCSRCS) $(HELLOWORLD_GWSRCS)
+examples: $(EXAMPLE_DEPSRCS) $(EXAMPLE_SVCSRCS) $(EXAMPLE_GWSRCS) $(EXAMPLE_OPENAPISRCS) $(EXAMPLE_OPENAPIMERGESRCS) $(EXAMPLE_CLIENT_SRCS) $(HELLOWORLD_SVCSRCS) $(HELLOWORLD_GWSRCS) $(GENERATE_UNBOUND_METHODS_EXAMPLE_GWSRCS) $(GENERATE_UNBOUND_METHODS_EXAMPLE_SVCSRCS) $(GENERATE_UNBOUND_METHODS_EXAMPLE_OPENAPISRCS)
 testproto: $(RUNTIME_TEST_SRCS) $(APICONFIG_SRCS)
 test: examples testproto
 	go test -short -race ./...
@@ -248,6 +270,9 @@ realclean: distclean
 	rm -f $(EXAMPLE_GWSRCS)
 	rm -f $(EXAMPLE_OPENAPISRCS)
 	rm -f $(EXAMPLE_CLIENT_SRCS)
+	rm -f $(GENERATE_UNBOUND_METHODS_EXAMPLE_GWSRCS)
+	rm -f $(GENERATE_UNBOUND_METHODS_EXAMPLE_SVCSRCS)
+	rm -f $(GENERATE_UNBOUND_METHODS_EXAMPLE_OPENAPISRCS)
 	rm -f $(HELLOWORLD_SVCSRCS)
 	rm -f $(HELLOWORLD_GWSRCS)
 	rm -f $(OPENAPIV2_GO)

README.md

@@ -97,8 +97,60 @@ Make sure that your `$GOBIN` is in your `$PATH`.
     }
    ```
 
-2. Add a [`google.api.http`](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto#L46)
-annotation to your .proto file
+2. Generate gRPC stubs
+
+    This step generates the gRPC stubs that you can use to implement the service and consume from clients:
+
+    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
+    ```
+
+3. Implement your service in gRPC as usual
+
+   1. (Optional) Generate gRPC stub in the [other programming languages](https://grpc.io/docs/).
+
+     For example, the following generates gRPC code for Ruby based on `your/service/v1/your_service.proto`:
+     ```sh
+     protoc -I . --ruby_out ./gen/ruby your/service/v1/your_service.proto
+
+     protoc -I . --grpc-ruby_out ./gen/ruby your/service/v1/your_service.proto
+     ```
+   2. Add the googleapis-common-protos gem (or your language equivalent) as a dependency to your project.
+   3. Implement your gRPC service stubs
+
+4. Generate reverse-proxy using `protoc-gen-grpc-gateway`
+
+    At this point, you have 3 options:
+
+    * no further modifications, use the default mapping to HTTP semantics (method, path, etc.)
+        * this will work on any `.proto` file, but will not allow setting HTTP paths, request parameters or similar
+    * additional `.proto` modifications to use a custom mapping
+        * relies on parameters in the `.proto` file to set custom HTTP mappings
+    * no `.proto` modifications, but use an external configuration file
+        * relies on an external configuration file to set custom HTTP mappings
+        * mostly useful when the source proto file isn't under your control
+
+    1. Using the default mapping
+
+    This requires no additional modification to the `.proto` file, but does require enabling a specific option when executing the plugin.
+    The `generate_unbound_methods` should be enabled.
+
+    Here's what a `protoc` execution might look like with this option enabled:
+
+    ```sh
+       protoc -I . --grpc-gateway_out ./gen/go \
+         --grpc-gateway_opt logtostderr=true \
+         --grpc-gateway_opt paths=source_relative \
+         --grpc-gateway_opt generate_unbound_methods=true \
+         your/service/v1/your_service.proto
+    ```
+
+    2. With custom annotations
+
+    Add a [`google.api.http`](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto#L46)
+    annotation to your .proto file
 
    `your_service.proto`:
    ```diff
@@ -131,68 +183,34 @@ annotation to your .proto file
    See [a_bit_of_everything.proto](examples/internal/proto/examplepb/a_bit_of_everything.proto)
    for examples of more annotations you can add to customize gateway behavior
    and generated OpenAPI output.
+   
+   Here's what a `protoc` execution might look like:
 
-   If you do not want to modify the proto file for use with grpc-gateway you can
+    ```sh
+       protoc -I . --grpc-gateway_out ./gen/go \
+         --grpc-gateway_opt logtostderr=true \
+         --grpc-gateway_opt paths=source_relative \
+         your/service/v1/your_service.proto
+    ```
+
+    3. External configuration
+   If you do not want to (or cannot) modify the proto file for use with grpc-gateway you can
    alternatively use an external
    [gRPC Service Configuration](https://cloud.google.com/endpoints/docs/grpc/grpc-service-config) file.
    [Check our documentation](https://grpc-ecosystem.github.io/grpc-gateway/docs/grpcapiconfiguration.html)
    for more information.
 
-3. Generate gRPC stub
-
-  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 protofiles 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.
-  
-  Here is an example of what a `protoc` command might look like:
-
-  ```sh
-  protoc -I. --go_out=plugins=grpc,paths=source_relative:./gen/go/ your/service/v1/your_service.proto
-  ```
+   Here's what a `protoc` execution might look like with this option enabled:
 
-  It will generate a stub file with path `./gen/go/your/service/v1/your_service.pb.go`.
+    ```sh
+       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/config.yaml \
+         your/service/v1/your_service.proto
+    ```
 
-4. Implement your service in gRPC as usual
-
-   1. (Optional) Generate gRPC stub in the [other programming languages](https://grpc.io/docs/).
-
-     For example, the following generates gRPC code for Ruby based on `your/service/v1/your_service.proto`:
-     ```sh
-     protoc -I. --ruby_out=./gen/ruby your/service/v1/your_service.proto
-
-     protoc -I. --grpc-ruby_out=./gen/ruby your/service/v1/your_service.proto
-     ```
-   2. Add the googleapis-common-protos gem (or your language equivalent) as a dependency to your project.
-   3. Implement your gRPC service stubs
-
-5. Generate reverse-proxy using `protoc-gen-grpc-gateway`
-
-   ```sh
-   protoc -I. --grpc-gateway_out=logtostderr=true,paths=source_relative:./gen/go \
-     your/service/v1/your_service.proto
-   ```
-
-   It will generate a reverse proxy `gen/go/your/service/v1/your_service.pb.gw.go`.
-   
-   OR generate a standalone reverse-proxy if needed.
-
-   Suppose you have a generated gRPC stub package, and you want to deploy several
-   API gateways using client-specific
-   [YAML annotations](https://grpc-ecosystem.github.io/grpc-gateway/docs/grpcapiconfiguration.html).
-   You can generate a grpc-gateway which imports the stub as an external 
-   package, so you don't have to regenerate it several times.
-   To set the import path of the stub package, set its full path in the `go_package`.
-   
-   ```sh
-   protoc -I. --grpc-gateway_out=logtostderr=true,grpc_api_configuration=apiOne.yaml,paths=source_relative,standalone=true:./gen/go/client_one \
-     your/service/v1/your_service.proto
-
-   protoc -I. --grpc-gateway_out=logtostderr=true,grpc_api_configuration=apiTwo.yaml,paths=source_relative,standalone=true:./gen/go/client_two \
-     your/service/v1/your_service.proto
-
-6. Write an entrypoint for the HTTP reverse-proxy server
+5. Write an entrypoint for the HTTP reverse-proxy server
 
    ```go
    package main
@@ -243,12 +261,14 @@ annotation to your .proto file
    }
    ```
 
-7. (Optional) Generate OpenAPI definitions using `protoc-gen-openapiv2`
+6. (Optional) Generate OpenAPI definitions using `protoc-gen-openapiv2`
 
    ```sh
-   protoc -I. --openapiv2_out=logtostderr=true:./gen/openapiv2 your/service/v1/your_service.proto
+   protoc -I . --openapiv2_out ./gen/openapiv2 --openapiv2_opt logtostderr=true your/service/v1/your_service.proto
    ```
 
+   Note that this plugin also supports generating swagger definitions for unannotated methods; use the `generate_unbound_methods` option to enable this.
+
 ## Video intro
 
 This GopherCon UK 2019 presentation from our maintainer
@@ -261,14 +281,27 @@ https://github.com/johanbrandhorst/grpc-gateway-boilerplate.
 ## Parameters and flags
 
 During code generation with `protoc`, flags to grpc-gateway tools must be passed
-through protoc using the `--<tool_suffix>_out=<flags>:<path>` pattern, for
-example:
+through protoc using one of 2 patterns:
+
+* as part of the `--<tool_suffix>_out` `protoc` parameter: `--<tool_suffix>_out=<flags>:<path>`
 
 ```sh
 --grpc-gateway_out=logtostderr=true,repeated_path_param_separator=ssv:.
 --openapiv2_out=logtostderr=true,repeated_path_param_separator=ssv:.
 ```
 
+* using additional `--<tool_suffix>_opt` parameters: `--<tool_suffix>_opt=<flag>[,<flag>]*`
+
+```sh
+--grpc-gateway_opt logtostderr=true,repeated_path_param_separator=ssv
+# or separately
+--grpc-gateway_opt logtostderr=true --grpc-gateway_opt repeated_path_param_separator=ssv
+
+--openapiv2_opt logtostderr=true,repeated_path_param_separator=ssv
+# or separately
+--openapiv2_opt logtostderr=true --openapiv2_opt repeated_path_param_separator=ssv
+```
+
 `protoc-gen-grpc-gateway` supports custom mapping from Protobuf `import` to
 Golang import paths. They are compatible with
 [the parameters with the same names in `protoc-gen-go`](https://github.com/golang/protobuf#parameters).

docs/_docs/grpcapiconfiguration.md

@@ -1,19 +1,36 @@
 ---
-title: Usage without annotations (gRPC API Configuration)
+title: Usage without annotations
 category: documentation
 order: 100
 ---
 
 # gRPC API Configuration
-In some situations annotating the .proto file of a service is not an option. For example you might not have control over the .proto file or you might want to expose the same gRPC API multiple times in completely different ways.
+In some situations annotating the .proto file of a service is not an option. For example, you might not have control over the .proto file, or you might want to expose the same gRPC API multiple times in completely different ways.
 
+`grpc-gateway` supports 2 ways of dealing with these situations:
+
+* [use the `generate_unbound_methods` option](#generate_unbound_methods)
+* [provide an external configuration file](#using-an-external-configuration-file) (gRPC API Configuration)
+
+## `generate_unbound_methods`
+
+Providing this parameter to the protoc plugin will make it produce the HTTP mapping even for methods without any `HttpRule` annotation.
+This is similar to how [Cloud Endpoints behaves](https://cloud.google.com/endpoints/docs/grpc/transcoding#where_to_configure_transcoding) and uses the way [gRPC itself](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md) maps to HTTP/2:
+
+* HTTP method is `POST`
+* 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.
+
+## 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.
 
 grpc-gateway generators implement the [HTTP rules part](https://cloud.google.com/endpoints/docs/grpc-service-config/reference/rpc/google.api#httprule) of this specification. This allows you to take a completely unannotated service proto file, add a YAML file describing its HTTP endpoints and use them together like a annotated proto file with the grpc-gateway generators.
 
 OpenAPI options may also be configured via ["OpenAPI Configuration"](https://github.com/grpc-ecosystem/grpc-gateway/tree/v2/internal/descriptor/openapiconfig/openapiconfig.proto) in the form of YAML configuration files.
 
-## Usage of gRPC API Configuration YAML files
+### Usage of gRPC API Configuration YAML files
 The following is equivalent to the basic [usage example](usage.html) but without direct annotation for grpc-gateway in the .proto file. Only some steps require minor changes to use a gRPC API Configuration YAML file instead:
 
 1. Define your service in gRPC as usual

examples/internal/clients/generateunboundmethods/.gitignore

@@ -0,0 +1 @@
+/docs

examples/internal/clients/generateunboundmethods/.swagger-codegen-ignore

@@ -0,0 +1 @@
+.gitignore

examples/internal/clients/generateunboundmethods/.swagger-codegen/VERSION

@@ -0,0 +1 @@
+2.4.8

examples/internal/clients/generateunboundmethods/BUILD.bazel

@@ -0,0 +1,18 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "go_default_library",
+    srcs = [
+        "api_generate_unbound_methods_echo_service.go",
+        "client.go",
+        "configuration.go",
+        "model_examplepb_generate_unbound_methods_simple_message.go",
+        "model_protobuf_any.go",
+        "model_rpc_status.go",
+        "model_runtime_error.go",
+        "response.go",
+    ],
+    importpath = "github.com/grpc-ecosystem/grpc-gateway/v2/examples/internal/clients/generateunboundmethods",
+    visibility = ["//examples:__subpackages__"],
+    deps = ["@org_golang_x_oauth2//:go_default_library"],
+)