1---
2title: Usage without annotations
3category: documentation
4order: 100
5---
6
7# gRPC API Configuration
8In 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.
9
10`grpc-gateway` supports 2 ways of dealing with these situations:
11
12* [use the `generate_unbound_methods` option](#generate_unbound_methods)
13* [provide an external configuration file](#using-an-external-configuration-file) (gRPC API Configuration)
14
15## `generate_unbound_methods`
16
17Providing this parameter to the protoc plugin will make it produce the HTTP mapping even for methods without any `HttpRule` annotation.
18This 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:
19
20* HTTP method is `POST`
21* URI path is built from the service's name and method: `/<fully qualified service name>/<method name>` (e.g.: `/my.package.EchoService/Echo`)
22* HTTP body is the serialized protobuf message.
23
24NOTE: the same option is also supported by the `gen-swagger` plugin.
25
26## Using an external configuration file
27Google 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.
28
29grpc-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.
30
31### Usage of gRPC API Configuration YAML files
32The 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:
33
341. Define your service in gRPC as usual
35
36 your_service.proto:
37 ```protobuf
38 syntax = "proto3";
39 package your.service.v1;
40 option go_package = "github.com/yourorg/yourprotos/gen/go/your/service/v1";
41 message StringMessage {
42 string value = 1;
43 }
44
45 service YourService {
46 rpc Echo(StringMessage) returns (StringMessage) {}
47 }
48 ```
49
502. Instead of annotating the .proto file in this step leave it untouched
51 and create a `your_service.yaml` with the following content:
52 ```yaml
53 type: google.api.Service
54 config_version: 3
55
56 http:
57 rules:
58 - selector: your.service.v1.YourService.Echo
59 post: /v1/example/echo
60 body: "*"
61 ```
62 Use a [linter](http://www.yamllint.com/) to validate your YAML.
63
643. Generate gRPC stub as before
65
66 ```sh
67 protoc -I. --go_out=plugins=grpc,paths=source_relative:./gen/go/ your/service/v1/your_service.proto
68 ```
69
70 It will generate a stub file with path `./gen/go/your/service/v1/your_service.pb.go`.
71
724. Implement your service in gRPC as usual
73
745. Generate the reverse-proxy. Here we have to pass the path to
75 the `your_service.yaml` in addition to the .proto file:
76
77 ```sh
78 protoc -I. --grpc-gateway_out=logtostderr=true,paths=source_relative,grpc_api_configuration=path/to/your_service.yaml:./gen/go \
79 your/service/v1/your_service.proto
80 ```
81
82 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.
83
846. Generate the optional your_service.swagger.json
85
86 ```sh
87 protoc -I. --swagger_out=grpc_api_configuration=path/to/your_service.yaml:./gen/go \
88 your/service/v1/your_service.proto
89 ```
90
91All 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.
View as plain text