+
diff --git a/docs/_imgs/gotemplates/postman.png b/docs/assets/images/gotemplates/postman.png
similarity index 100%
rename from docs/_imgs/gotemplates/postman.png
rename to docs/assets/images/gotemplates/postman.png
diff --git a/docs/_imgs/gotemplates/swaggerui.png b/docs/assets/images/gotemplates/swaggerui.png
similarity index 100%
rename from docs/_imgs/gotemplates/swaggerui.png
rename to docs/assets/images/gotemplates/swaggerui.png
diff --git a/docs/_docs/aws.md b/docs/docs/aws.md
similarity index 95%
rename from docs/_docs/aws.md
rename to docs/docs/aws.md
index 33d3a51cbf6..8771304558e 100644
--- a/docs/_docs/aws.md
+++ b/docs/docs/aws.md
@@ -1,10 +1,13 @@
---
-category: documentation
+layout: default
+title: AWS
+nav_order: 2
---
# AWS
## Import OpenAPI documentation into AWS API Gateway
+
The AWS API gateway service allows importing of an OpenAPI specification to create a REST API. The process is very straightforward and can be found [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html).
Here are some tips to consider when importing the documentation:
diff --git a/docs/_docs/background.md b/docs/docs/background.md
similarity index 93%
rename from docs/_docs/background.md
rename to docs/docs/background.md
index 63463a1ba0f..6a066610f7a 100644
--- a/docs/_docs/background.md
+++ b/docs/docs/background.md
@@ -1,5 +1,7 @@
---
-category: documentation
+layout: default
+title: Background
+nav_order: 3
---
# Background
@@ -8,4 +10,3 @@ gRPC is great -- it generates API clients and server stubs in many programming l
However, you might still want to provide a traditional RESTful API as well. Reasons can range from maintaining backwards-compatibility, supporting languages or clients not well supported by gRPC to simply maintaining the aesthetics and tooling involved with a RESTful architecture.
This project aims to provide that HTTP+JSON interface to your gRPC service. A small amount of configuration in your service to attach HTTP semantics is all that's needed to generate a reverse-proxy with this library.
-
diff --git a/docs/_docs/customizingyourgateway.md b/docs/docs/customizingyourgateway.md
similarity index 91%
rename from docs/_docs/customizingyourgateway.md
rename to docs/docs/customizingyourgateway.md
index 2be1b795ee8..f1f31d722ab 100644
--- a/docs/_docs/customizingyourgateway.md
+++ b/docs/docs/customizingyourgateway.md
@@ -1,25 +1,26 @@
---
+layout: default
title: Customizing your gateway
-category: documentation
-order: 101
+nav_order: 4
---
# Customizing your gateway
## Message serialization
+
### Custom serializer
You might want to serialize request/response messages in MessagePack instead of JSON, for example.
1. Write a custom implementation of [`Marshaler`](https://pkg.go.dev/github.com/grpc-ecosystem/grpc-gateway/runtime?tab=doc#Marshaler)
2. Register your marshaler with [`WithMarshalerOption`](https://pkg.go.dev/github.com/grpc-ecosystem/grpc-gateway/runtime?tab=doc#WithMarshalerOption)
- e.g.
- ```go
- var m your.MsgPackMarshaler
- mux := runtime.NewServeMux(
- runtime.WithMarshalerOption("application/x-msgpack", m),
- )
- ```
+ e.g.
+ ```go
+ var m your.MsgPackMarshaler
+ mux := runtime.NewServeMux(
+ runtime.WithMarshalerOption("application/x-msgpack", m),
+ )
+ ```
You can see [the default implementation for JSON](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/runtime/marshal_jsonpb.go) for reference.
@@ -27,6 +28,7 @@ You can see [the default implementation for JSON](https://github.com/grpc-ecosys
The protocol buffer compiler generates camelCase JSON tags that are used by default.
If you want to use the exact case used in the proto files, set `UseProtoNames: true`:
+
```go
mux := runtime.NewServeMux(
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{
@@ -45,7 +47,7 @@ mux := runtime.NewServeMux(
You can have Elasticsearch-style `?pretty` support in your gateway's endpoints as follows:
1. Wrap the ServeMux using a stdlib [`http.HandlerFunc`](https://golang.org/pkg/net/http/#HandlerFunc)
- that translates the provided query parameter into a custom `Accept` header, and
+ that translates the provided query parameter into a custom `Accept` header, and
2. Register a pretty-printing marshaler for that MIME code.
For example:
@@ -97,28 +99,30 @@ mux := runtime.NewServeMux(
```
## Mapping from HTTP request headers to gRPC client metadata
+
You might not like [the default mapping rule](https://pkg.go.dev/github.com/grpc-ecosystem/grpc-gateway/runtime?tab=doc#DefaultHeaderMatcher) and might want to pass through all the HTTP headers, for example.
1. Write a [`HeaderMatcherFunc`](https://pkg.go.dev/github.com/grpc-ecosystem/grpc-gateway/runtime?tab=doc#HeaderMatcherFunc).
2. Register the function with [`WithIncomingHeaderMatcher`](https://pkg.go.dev/github.com/grpc-ecosystem/grpc-gateway/runtime?tab=doc#WithIncomingHeaderMatcher)
- e.g.
- ```go
- func CustomMatcher(key string) (string, bool) {
- switch key {
- case "X-Custom-Header1":
- return key, true
- case "X-Custom-Header2":
- return "custom-header2", true
- default:
- return key, false
- }
- }
-
- mux := runtime.NewServeMux(
- runtime.WithIncomingHeaderMatcher(CustomMatcher),
- )
- ```
+ e.g.
+
+ ```go
+ func CustomMatcher(key string) (string, bool) {
+ switch key {
+ case "X-Custom-Header1":
+ return key, true
+ case "X-Custom-Header2":
+ return "custom-header2", true
+ default:
+ return key, false
+ }
+ }
+
+ mux := runtime.NewServeMux(
+ runtime.WithIncomingHeaderMatcher(CustomMatcher),
+ )
+ ```
To keep the [the default mapping rule](https://pkg.go.dev/github.com/grpc-ecosystem/grpc-gateway/runtime?tab=doc#DefaultHeaderMatcher) alongside with your own rules write:
@@ -132,16 +136,21 @@ func CustomMatcher(key string) (string, bool) {
}
}
```
+
It will work with both:
```shell
$ curl --header "x-user-id: 100d9f38-2777-4ee2-ac3b-b3a108f81a30" ...
```
+
and:
+
```shell
$ curl --header "X-USER-ID: 100d9f38-2777-4ee2-ac3b-b3a108f81a30" ...
```
+
To access this header on gRPC server side use:
+
```go
userID := ""
if md, ok := metadata.FromIncomingContext(ctx); ok {
@@ -152,9 +161,11 @@ if md, ok := metadata.FromIncomingContext(ctx); ok {
```
## Mapping from gRPC server metadata to HTTP response headers
+
ditto. Use [`WithOutgoingHeaderMatcher`](https://pkg.go.dev/github.com/grpc-ecosystem/grpc-gateway/runtime?tab=doc#WithOutgoingHeaderMatcher).
See [gRPC metadata docs](https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md)
for more info on sending / receiving gRPC metadata, e.g.
+
```go
if appendCustomHeader {
grpc.SendHeader(ctx, metadata.New(map[string]string{
@@ -164,7 +175,9 @@ if appendCustomHeader {
```
## Mutate response messages or set response headers
+
### Set HTTP headers
+
You might want to return a subset of response fields as HTTP response headers;
You might want to simply set an application-specific token in a header.
Or you might want to mutate the response messages to be returned.
@@ -181,15 +194,19 @@ func myFilter(ctx context.Context, w http.ResponseWriter, resp proto.Message) er
return nil
}
```
+
2. Register the filter with [`WithForwardResponseOption`](https://pkg.go.dev/github.com/grpc-ecosystem/grpc-gateway/runtime?tab=doc#WithForwardResponseOption)
e.g.
+
```go
mux := runtime.NewServeMux(
runtime.WithForwardResponseOption(myFilter),
)
```
+
### Controlling HTTP response status codes
+
To have the most control over the HTTP response status codes, you can use custom metadata.
While handling the rpc, set the intended status code:
@@ -198,10 +215,11 @@ While handling the rpc, set the intended status code:
grpc.SetHeader(ctx, metadata.Pairs("x-http-code", "401"))
```
-Now, before sending the HTTP response, we need to check for this metadata pair and explicitly set the status code for the response if found.
+Now, before sending the HTTP response, we need to check for this metadata pair and explicitly set the status code for the response if found.
To do so, create a function and hook it into the grpc-gateway as a Forward Response Option.
The function looks like this:
+
```go
func httpResponseModifier(ctx context.Context, w http.ResponseWriter, p proto.Message) error {
md, ok := runtime.ServerMetadataFromContext(ctx)
@@ -234,6 +252,7 @@ gwMux := runtime.NewServeMux(
```
## Error handler
+
To override error handling for a `*runtime.ServeMux`, use the
`runtime.WithErrorHandler` option. This will configure all unary error
responses to pass through this error handler.
@@ -244,6 +263,7 @@ the v1 release of the gateway, and you no longer assign to `HTTPError` to
configure an error handler.
## Stream Error Handler
+
The error handler described in the previous section applies only
to RPC methods that have a unary response.
@@ -272,6 +292,7 @@ can choose to omit some fields and can filter/transform the original
error, such as stripping stack traces from error messages.
Here's an example custom handler:
+
```go
// handleStreamError overrides default behavior for computing an error
// message for a server stream.
@@ -305,15 +326,17 @@ if the error being reported includes them. If the error does not have
these attributes, a gRPC code of `Unknown` (2) is reported.
## Routing Error handler
-To override the error behavior when `*runtime.ServeMux` was not
-able to serve the request due to routing issues, use the `runtime.WithRoutingErrorHandler` option.
+
+To override the error behavior when `*runtime.ServeMux` was not
+able to serve the request due to routing issues, use the `runtime.WithRoutingErrorHandler` option.
This will configure all HTTP routing errors to pass through this error handler.
Default behavior is to map HTTP error codes to gRPC errors.
-HTTP statuses and their mappings to gRPC statuses:
-* HTTP `404 Not Found` -> gRPC `5 NOT_FOUND`
-* HTTP `405 Method Not Allowed` -> gRPC `12 UNIMPLEMENTED`
-* HTTP `400 Bad Request` -> gRPC `3 INVALID_ARGUMENT`
+HTTP statuses and their mappings to gRPC statuses:
+
+- HTTP `404 Not Found` -> gRPC `5 NOT_FOUND`
+- HTTP `405 Method Not Allowed` -> gRPC `12 UNIMPLEMENTED`
+- HTTP `400 Bad Request` -> gRPC `3 INVALID_ARGUMENT`
This method is not used outside of the initial routing.
diff --git a/docs/_docs/cygwin.md b/docs/docs/cygwin.md
similarity index 99%
rename from docs/_docs/cygwin.md
rename to docs/docs/cygwin.md
index 3963698c8c1..697fe7ba832 100644
--- a/docs/_docs/cygwin.md
+++ b/docs/docs/cygwin.md
@@ -1,7 +1,7 @@
---
-category: documentation
+layout: default
title: Installation for Cygwin
-order: 1000
+nav_order: 5
---
# Installation for Cygwin
diff --git a/docs/_docs/examples.md b/docs/docs/examples.md
similarity index 81%
rename from docs/_docs/examples.md
rename to docs/docs/examples.md
index cf22cc3d7ec..cfa70cbb066 100644
--- a/docs/_docs/examples.md
+++ b/docs/docs/examples.md
@@ -1,27 +1,30 @@
---
-category: documentation
+layout: default
+title: Examples
+nav_order: 6
---
# Examples
Examples are available under `examples/internal` directory.
-* [`proto/examplepb/echo_service.proto`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/echo_service.proto),
+
+- [`proto/examplepb/echo_service.proto`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/echo_service.proto),
[`proto/examplepb/a_bit_of_everything.proto`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/a_bit_of_everything.proto),
[`proto/examplepb/unannotated_echo_service.proto`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/unannotated_echo_service.proto):
protobuf service definitions.
-* [`proto/examplepb/echo_service.pb.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/echo_service.pb.go),
+- [`proto/examplepb/echo_service.pb.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/echo_service.pb.go),
[`proto/examplepb/a_bit_of_everything.pb.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/a_bit_of_everything.pb.go),
[`proto/examplepb/unannotated_echo_service.pb.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/unannotated_echo_service.pb.go):
generated Go service stubs and types.
-* [`proto/examplepb/echo_service.pb.gw.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/echo_service.pb.gw.go),
+- [`proto/examplepb/echo_service.pb.gw.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/echo_service.pb.gw.go),
[`proto/examplepb/a_bit_of_everything.pb.gw.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/a_bit_of_everything.pb.gw.go),
[`proto/examplepb/uannotated_echo_service.pb.gw.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/uannotated_echo_service.pb.gw.go):
generated gRPC-gateway clients.
- * [`proto/examplepb/unannotated_echo_service.yaml`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/uannotated_echo_service.yaml):
- gRPC API Configuration for `unannotated_echo_service.proto`.
-* [`server/main.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/server/main.go):
+ - [`proto/examplepb/unannotated_echo_service.yaml`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/proto/examplepb/uannotated_echo_service.yaml):
+ gRPC API Configuration for `unannotated_echo_service.proto`.
+- [`server/main.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/server/main.go):
service implementation.
-* [`main.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/gateway/main.go):
+- [`main.go`](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/examples/internal/gateway/main.go):
entrypoint of the generated reverse proxy.
To use the same port for custom HTTP handlers (e.g. serving `swagger.json`),
@@ -29,5 +32,3 @@ gRPC-gateway, and a gRPC server, see
[this code example by CoreOS](https://github.com/philips/grpc-gateway-example/blob/master/cmd/serve.go)
(and its accompanying
[blog post](https://coreos.com/blog/grpc-protobufs-swagger.html))
-
-
diff --git a/docs/_docs/faq.md b/docs/docs/faq.md
similarity index 98%
rename from docs/_docs/faq.md
rename to docs/docs/faq.md
index 30e34011428..5457f350e04 100644
--- a/docs/_docs/faq.md
+++ b/docs/docs/faq.md
@@ -1,11 +1,13 @@
---
-category: documentation
+layout: default
title: FAQ
+nav_order: 7
---
# FAQ
## How can I write the annotations which grpc-gateway requires?
+
The gRPC-Gateway follows the spec of
[`google.api.HttpRule`](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto),
so first check out the documentation if it is feasible in the spec.
@@ -14,6 +16,7 @@ See also [a past discussion](https://groups.google.com/d/msg/grpc-io/Xqx80hG0D44
in the grpc-io mailing list.
## I want to support a certain style of HTTP request but the code generated by grpc-gateway does not. How can I support this style?
+
See the question above at first.
The gRPC-Gateway is intended to cover 80% of use cases without forcing you to write comprehensive but
diff --git a/docs/_docs/grpcapiconfiguration.md b/docs/docs/grpcapiconfiguration.md
similarity index 52%
rename from docs/_docs/grpcapiconfiguration.md
rename to docs/docs/grpcapiconfiguration.md
index fbb51920869..2195a7cb995 100644
--- a/docs/_docs/grpcapiconfiguration.md
+++ b/docs/docs/grpcapiconfiguration.md
@@ -1,29 +1,31 @@
---
-title: Usage without annotations
-category: documentation
-order: 100
+layout: default
+title: gRPC API Configuration
+nav_order: 8
---
# 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.
`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)
+- [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: `//` (e.g.: `/my.package.EchoService/Echo`)
-* HTTP body is the serialized protobuf message.
+- HTTP method is `POST`
+- 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-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.
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.
@@ -31,90 +33,94 @@ grpc-gateway generators implement the [HTTP rules part](https://cloud.google.com
OpenAPI options may also be configured via ["OpenAPI Configuration"](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/internal/descriptor/openapiconfig/openapiconfig.proto) in the form of YAML configuration 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
- your_service.proto:
- ```protobuf
- syntax = "proto3";
- package your.service.v1;
- option go_package = "github.com/yourorg/yourprotos/gen/go/your/service/v1";
- message StringMessage {
- string value = 1;
- }
+ your_service.proto:
- service YourService {
- rpc Echo(StringMessage) returns (StringMessage) {}
- }
- ```
+ ```protobuf
+ 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:
- ```yaml
- type: google.api.Service
- config_version: 3
-
- http:
- rules:
- - selector: your.service.v1.YourService.Echo
- post: /v1/example/echo
- body: "*"
- ```
- Use a [linter](http://www.yamllint.com/) to validate your YAML.
+
+ ```yaml
+ type: google.api.Service
+ config_version: 3
+
+ http:
+ rules:
+ - 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 . \
- --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
- ```
+ ```sh
+ 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`.
+It will generate a stub file with path `./gen/go/your/service/v1/your_service.pb.go`.
4. Implement your service in gRPC as usual
5. Generate the reverse-proxy. Here we have to pass the path to
- the `your_service.yaml` in addition to the .proto file:
+ the `your_service.yaml` in addition to the .proto file:
- ```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/your_service.yaml \
- your/service/v1/your_service.proto
- ```
+ ```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/your_service.yaml \
+ 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.
6. Generate the optional your_service.swagger.json
- ```sh
- 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 . --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 . --openapiv2_out ./gen/go \
- --openapiv2_opt grpc_api_configuration=path/to/your_service.yaml \
- your/service/v1/your_service.proto
- ```
-
+ ```sh
+ 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 . --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 . --openapiv2_out ./gen/go \
+ --openapiv2_opt grpc_api_configuration=path/to/your_service.yaml \
+ your/service/v1/your_service.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.
diff --git a/docs/_docs/healthcheck.md b/docs/docs/healthcheck.md
similarity index 94%
rename from docs/_docs/healthcheck.md
rename to docs/docs/healthcheck.md
index 7dd54e9f60e..8dea546298f 100644
--- a/docs/_docs/healthcheck.md
+++ b/docs/docs/healthcheck.md
@@ -1,5 +1,7 @@
---
-category: documentation
+layout: default
+title: Health Check
+nav_order: 9
---
# Health check
@@ -23,7 +25,7 @@ func (s *serviceServer) Check(ctx context.Context, in *health.HealthCheckRequest
}
```
-2. Watch method
+2. Watch method
```
func (s *serviceServer) Watch(in *health.HealthCheckRequest, _ health.Health_WatchServer) error {
diff --git a/docs/_docs/httpbody.md b/docs/docs/httpbody.md
similarity index 96%
rename from docs/_docs/httpbody.md
rename to docs/docs/httpbody.md
index 62ebf49179d..c948f185d1d 100644
--- a/docs/_docs/httpbody.md
+++ b/docs/docs/httpbody.md
@@ -1,5 +1,7 @@
---
-category: documentation
+layout: default
+title: HttpBody messages
+nav_order: 10
---
# HttpBody messages
diff --git a/docs/_docs/inject_router.md b/docs/docs/inject_router.md
similarity index 97%
rename from docs/_docs/inject_router.md
rename to docs/docs/inject_router.md
index a3420e92c3e..cc9532acd6c 100644
--- a/docs/_docs/inject_router.md
+++ b/docs/docs/inject_router.md
@@ -1,6 +1,7 @@
---
-category: documentation
+layout: default
title: Adding custom routes to the mux
+nav_order: 11
---
# Adding custom routes to the mux
@@ -15,7 +16,7 @@ package main
import (
"context"
"net/http"
-
+
pb "github.com/grpc-ecosystem/grpc-gateway/v2/examples/internal/helloworld"
"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
)
@@ -41,7 +42,7 @@ func main() {
// GreeterServer is the server API for Greeter service.
type GreeterServer struct {
-
+
}
// SayHello implement to say hello
@@ -50,4 +51,4 @@ func (h *GreeterServer) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb
Message: "hello " + req.Name,
}, nil
}
-```
\ No newline at end of file
+```
diff --git a/docs/docs/patch.md b/docs/docs/patch.md
new file mode 100644
index 00000000000..7a880e60c1d
--- /dev/null
+++ b/docs/docs/patch.md
@@ -0,0 +1,99 @@
+---
+layout: default
+title: Patch Feature
+nav_order: 12
+---
+
+# Patch Feature
+
+The HTTP PATCH method allows a resource to be partially updated.
+
+If a binding is mapped to patch and the request message has exactly one
+FieldMask message in it, additional code is rendered for the gateway
+handler that will populate the FieldMask based on the request body.
+
+There are two scenarios:
+
+- The FieldMask is hidden from the REST request as per the
+ [Google API design guide](https://cloud.google.com/apis/design/standard_methods#update)
+ (as in the first additional binding in the
+ [UpdateV2](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto#L366)
+ example).
+ In this case, the FieldMask is updated from the request body and
+ set in the gRPC request message.
+- The FieldMask is exposed to the REST request (as in the second
+ additional binding in the
+ [UpdateV2](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto#L370)
+ example).
+ For this case, the field mask is left untouched by the gateway.
+
+## Example Usage
+
+1. Create PATCH request.
+
+ The PATCH request needs to include the message and the update mask.
+
+ ```protobuf
+ // UpdateV2Request request for update includes the message and the update mask
+ message UpdateV2Request {
+ ABitOfEverything abe = 1;
+ google.protobuf.FieldMask update_mask = 2;
+ }
+ ```
+
+2. Define your service in gRPC
+
+ If you want to use PATCH with fieldmask hidden from REST request only include the request message in the body.
+
+ ```protobuf
+ rpc UpdateV2(UpdateV2Request) returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ put: "/v2/example/a_bit_of_everything/{abe.uuid}"
+ body: "abe"
+ additional_bindings {
+ patch: "/v2/example/a_bit_of_everything/{abe.uuid}"
+ body: "abe"
+ }
+ };
+ }
+ ```
+
+ If you want to use PATCH with fieldmask exposed to the REST request then include the entire request message.
+
+ ```protobuf
+ rpc UpdateV2(UpdateV2Request) returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ patch: "/v2a/example/a_bit_of_everything/{abe.uuid}"
+ body: "*"
+ };
+ }
+ ```
+
+3. Generate gRPC and reverse-proxy stubs and implement your service.
+
+## Curl examples
+
+In the example below we will partially update our ABitOfEverything
+resource by passing only the field we want to change. Since we are
+using the endpoint with field mask hidden we only need to pass the
+field we want to change ("string_value") and it will keep everything
+else in our resource the same.
+
+```shell
+$ curl \
+ --data '{"string_value": "strprefix/foo"}' \
+ -X PATCH \
+ http://address:port/v2/example/a_bit_of_everything/1
+```
+
+If we know what fields we want to update then we can use PATCH with
+field mask approach. For this we need to pass the resource and the
+update_mask. Below only the "single_nested" will get updated because
+that is what we specify in the field_mask.
+
+```shell
+$ curl \
+ --data '{"abe":{"single_nested":{"amount":457},"string_value":"some value that won't get updated because not in the field mask"},"update_mask":{"paths":["single_nested"]}}' \
+ -X PATCH \
+ http://address:port/v2a/example/a_bit_of_everything/1
+```
diff --git a/docs/_docs/season_of_docs.md b/docs/docs/season_of_docs.md
similarity index 59%
rename from docs/_docs/season_of_docs.md
rename to docs/docs/season_of_docs.md
index 4e8afcb9e90..6515d7a8078 100644
--- a/docs/_docs/season_of_docs.md
+++ b/docs/docs/season_of_docs.md
@@ -1,6 +1,7 @@
---
-category: documentation
-name: 2020 Season of Docs
+layout: default
+title: 2020 Season of Docs
+nav_order: 13
---
# 2020 Season of Docs
@@ -12,18 +13,18 @@ We're excited to see what contributions this will bring to our documentation.
## Project details
- - Organization name: **gRPC-Gateway**
- - Organization description: The gRPC-Gateway brings the power and safety of designing APIs with Protobuf and gRPC to the JSON/HTTP API world. It has several
- common use cases:
- - When a user wants to migrate an API to gRPC, but needs to expose a JSON/HTTP API
- to old users.
- - When a user wants to expose an existing gRPC API to a JSON/HTTP API audience.
- - When quickly iterating on a JSON/HTTP API design.
- - Website: https://grpc-ecosystem.github.io/grpc-gateway
- - Repo: https://github.com/grpc-ecosystem/grpc-gateway
- - Project administrators and mentors:
- - Johan Brandhorst (@johanbrandhorst)
- - Andrew Z Allen (@achew22)
+- Organization name: **gRPC-Gateway**
+- Organization description: The gRPC-Gateway brings the power and safety of designing APIs with Protobuf and gRPC to the JSON/HTTP API world. It has several
+ common use cases:
+ - When a user wants to migrate an API to gRPC, but needs to expose a JSON/HTTP API
+ to old users.
+ - When a user wants to expose an existing gRPC API to a JSON/HTTP API audience.
+ - When quickly iterating on a JSON/HTTP API design.
+- Website: https://grpc-ecosystem.github.io/grpc-gateway
+- Repo: https://github.com/grpc-ecosystem/grpc-gateway
+- Project administrators and mentors:
+ - Johan Brandhorst (@johanbrandhorst)
+ - Andrew Z Allen (@achew22)
## Project Ideas
@@ -42,11 +43,12 @@ try to use the current material and note anything that was unclear and that they
easily find with our existing docs.
Material:
- - [The current site](https://grpc-ecosystem.github.io/grpc-gateway/)
- - [Jekyll](https://jekyllrb.com/) which powers the site now.
- - [The source code](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/docs) for the site today.
- - [The project README](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/README.md) which
- contains an intro to the project.
+
+- [The current site](https://grpc-ecosystem.github.io/grpc-gateway/)
+- [Jekyll](https://jekyllrb.com/) which powers the site now.
+- [The source code](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/docs) for the site today.
+- [The project README](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/README.md) which
+ contains an intro to the project.
### Rewrite the README with a better intro and examples
@@ -54,25 +56,26 @@ The README has evolved since the start of the project and could do with a rewrit
first principles. The README is the first thing our prospective users see, and it should
quickly and concisely answer the most important questions for our users.
- - What problems can the gRPC-Gateway solve?
- - How do I use the gRPC-Gateway?
- - What does a complete example look like?
- - Where can I find more information about using it?
- - Where can I learn more about the technologies the gRPC-Gateway is built on?
- - How do I submit an issue report or get help?
+- What problems can the gRPC-Gateway solve?
+- How do I use the gRPC-Gateway?
+- What does a complete example look like?
+- Where can I find more information about using it?
+- Where can I learn more about the technologies the gRPC-Gateway is built on?
+- How do I submit an issue report or get help?
Material:
- - [The current README](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/README.md).
+
+- [The current README](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/README.md).
### Create a tutorial for the docs site
We'd like to be able to point to a tutorial for one of the common use cases of the project.
The ones mentioned in the project details are the primary use cases we advertise:
- - When a user wants to migrate an API to gRPC, but needs to expose a JSON/HTTP API
- to old users.
- - When a user wants to expose an existing gRPC API to a JSON/HTTP API audience.
- - When quickly iterating on an JSON/HTTP API design.
+- When a user wants to migrate an API to gRPC, but needs to expose a JSON/HTTP API
+ to old users.
+- When a user wants to expose an existing gRPC API to a JSON/HTTP API audience.
+- When quickly iterating on an JSON/HTTP API design.
It could be a single or several blog posts on our docs site, or another site, like Medium.
@@ -84,7 +87,8 @@ to have a look over this and add detail where possible and generally structure i
a bit better. Maybe it could be rewritten as a FAQ that details solutions to common issues?
Material:
- - [The customize your gateway page](https://grpc-ecosystem.github.io/grpc-gateway/docs/customizingyourgateway.html)
+
+- [The customize your gateway page](https://grpc-ecosystem.github.io/grpc-gateway/docs/customizingyourgateway.html)
### Improve the contributor's guide
@@ -94,8 +98,9 @@ and the [issue templates](https://github.com/grpc-ecosystem/grpc-gateway/tree/ma
Both of these are a little ad-hoc and could do with a fresh pair of eyes.
Material:
- - [Current CONTRIBUTING.md](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md)
- - [Current issue templates](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/.github/ISSUE_TEMPLATE)
+
+- [Current CONTRIBUTING.md](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md)
+- [Current issue templates](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/.github/ISSUE_TEMPLATE)
### Write a v2.0.0 migration guide
@@ -104,11 +109,12 @@ We need to write a migration guide so that users know what to expect when upgrad
This should include:
- - A list of all the breaking changes and their consequences for the user.
- - For each breaking change, a guide to how their systems may need to be changed.
+- A list of all the breaking changes and their consequences for the user.
+- For each breaking change, a guide to how their systems may need to be changed.
Currently, the scope of the v2 release is not entirely known, as it is still in progress, but we will
endeavour not to make too many breaking changes as that will discourage users from upgrading.
Material:
- - [v2 Tracking issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/1223)
+
+- [v2 Tracking issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/1223)
diff --git a/docs/_docs/tracing.md b/docs/docs/tracing.md
similarity index 98%
rename from docs/_docs/tracing.md
rename to docs/docs/tracing.md
index b6a641c20ed..58183065dac 100644
--- a/docs/_docs/tracing.md
+++ b/docs/docs/tracing.md
@@ -1,5 +1,7 @@
---
-category: documentation
+layout: default
+title: Tracing
+nav_order: 14
---
# Tracing
@@ -8,7 +10,7 @@ category: documentation
#### Adding tracing using AWS-Xray as the exporter
-This example uses the AWS-Xray exporter with a global trace setting. Note that AWS X-ray exporter does not handle any metrics only tracing.
+This example uses the AWS-Xray exporter with a global trace setting. Note that AWS X-ray exporter does not handle any metrics only tracing.
1. Add the following imports
@@ -57,6 +59,7 @@ conn, err := grpc.DialContext(
```
5. Wrap the gateway mux with the OpenCensus HTTP handler
+
```go
gwmux := runtime.NewServeMux()
@@ -97,8 +100,8 @@ openCensusHandler := &ochttp.Handler{
4. No global configuration means we have to use the [per span sampler](https://opencensus.io/tracing/sampling/#per-span-sampler)
-
##### A method we want to trace
+
```go
func (s *service) Name(ctx context.Context, req *pb.Request) (*pb.Response, error) {
// Here we add the span ourselves.
@@ -111,6 +114,7 @@ func (s *service) Name(ctx context.Context, req *pb.Request) (*pb.Response, erro
```
##### A method we do not wish to trace
+
```go
func (s *service) Check(ctx context.Context, in *health.HealthCheckRequest) (*health.HealthCheckResponse, error) {
// Note no span here.
@@ -174,4 +178,4 @@ opts := []grpc.DialOption{
if err := pb.RegisterMyServiceHandlerFromEndpoint(ctx, mux, serviceEndpoint, opts); err != nil {
log.Fatalf("could not register HTTP service: %v", err)
}
-```
\ No newline at end of file
+```
diff --git a/docs/_docs/usage.md b/docs/docs/usage.md
similarity index 66%
rename from docs/_docs/usage.md
rename to docs/docs/usage.md
index 949daf88d87..4d63ed62016 100644
--- a/docs/_docs/usage.md
+++ b/docs/docs/usage.md
@@ -1,5 +1,7 @@
---
-category: documentation
+layout: default
+title: How do I use this?
+nav_order: 15
---
# How do I use this?
diff --git a/docs/_docs/usegotemplates.md b/docs/docs/usegotemplates.md
similarity index 83%
rename from docs/_docs/usegotemplates.md
rename to docs/docs/usegotemplates.md
index 2ed630201be..009f082a2af 100644
--- a/docs/_docs/usegotemplates.md
+++ b/docs/docs/usegotemplates.md
@@ -1,16 +1,20 @@
---
-category: documentation
-name: Use go templates in protofile comments
+layout: default
+title: Use go templates in protofile comments
+nav_order: 16
---
+{% raw %}
+
# Use go templates in protofile comments
Use [Go templates](https://golang.org/pkg/text/template/)
in your protofile comments to allow more advanced documentation such
-as:
-* Documentation about fields in the proto objects.
-* Import the content of external files (such as
- [Markdown](https://en.wikipedia.org/wiki/Markdown)).
+as:
+
+- Documentation about fields in the proto objects.
+- Import the content of external files (such as
+ [Markdown](https://en.wikipedia.org/wiki/Markdown)).
## How to use it
@@ -38,16 +42,17 @@ $ protoc -I. \
--openapiv2_out . \
--openapiv2_opt logtostderr=true \
--openapiv2_opt use_go_templates=true \
- path/to/my/proto/v1/myproto.proto
+ path/to/my/proto/v1/myproto.proto
```
### Example proto file
Example of a protofile with Go templates. This proto file imports documentation from another file, `tables.md`:
+
```protobuf
service LoginService {
// Login
- //
+ //
// {{.MethodDescriptorProto.Name}} is a call with the method(s) {{$first := true}}{{range .Bindings}}{{if $first}}{{$first = false}}{{else}}, {{end}}{{.HTTPMethod}}{{end}} within the "{{.Service.Name}}" service.
// It takes in "{{.RequestType.Name}}" and returns a "{{.ResponseType.Name}}".
//
@@ -61,7 +66,7 @@ service LoginService {
}
message LoginRequest {
- // The entered username
+ // The entered username
string username = 1;
// The entered password
string password = 2;
@@ -93,13 +98,15 @@ The content of `tables.md`:
This is how the OpenAPI file would be rendered in [Swagger UI](https://swagger.io/tools/swagger-ui/)
-
+
### Postman
This is how the OpenAPI file would be rendered in [Postman](https://www.getpostman.com/)
-
+
For a more detailed example of a protofile that has Go templates enabled,
[see the examples](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/use_go_template.proto).
+
+{% endraw %}
diff --git a/docs/_docs/v2-migration.md b/docs/docs/v2-migration.md
similarity index 98%
rename from docs/_docs/v2-migration.md
rename to docs/docs/v2-migration.md
index 35d72e2498f..22e704c91c0 100644
--- a/docs/_docs/v2-migration.md
+++ b/docs/docs/v2-migration.md
@@ -1,6 +1,7 @@
---
-title: v2 migration guide
-category: documentation
+layout: default
+title: gRPC-Gateway v2 migration guide
+nav_order: 17
---
# gRPC-Gateway v2 migration guide
@@ -21,15 +22,21 @@ difference to users will be a slightly different proto annotation:
```protobuf
import "protoc-gen-openapiv2/options/annotations.proto";
```
+
instead of
+
```protobuf
import "protoc-gen-swagger/options/annotations.proto";
```
+
and
+
```protobuf
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
```
+
instead of
+
```protobuf
option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
```
@@ -58,6 +65,7 @@ example: "{\"uuid\": \"0cf361e1-4b44-483d-a159-54dabdf7e814\"}"
See `a_bit_of_everything.proto` in the example protos for more examples.
## We now use the camelCase JSON names by default
+
See
[the original issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/375)
and
@@ -66,6 +74,7 @@ for more information.
If you want to revert to the old behaviour, configure a custom marshaler with
`UseProtoNames: true`:
+
```go
mux := runtime.NewServeMux(
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.HTTPBodyMarshaler{
@@ -97,6 +106,7 @@ for more information.
If you want to revert to the old behaviour, configure a custom marshaler with
`EmitUnpopulated: false`:
+
```go
mux := runtime.NewServeMux(
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.HTTPBodyMarshaler{
@@ -169,5 +179,5 @@ services.
`runtime.WithProtoErrorHandler` are all gone. Error handling is rewritten around the
use of gRPCs Status types. If you wish to configure how the gateway handles errors,
please use `runtime.WithErrorHandler` and `runtime.WithStreamErrorHandler`.
-To handle routing errors (similar to the removed `runtime.OtherErrorHandler`) please use
+To handle routing errors (similar to the removed `runtime.OtherErrorHandler`) please use
`runtime.WithRoutingErrorHandler`.
diff --git a/docs/favicon.ico b/docs/favicon.ico
new file mode 100644
index 00000000000..d52f5093085
Binary files /dev/null and b/docs/favicon.ico differ
diff --git a/docs/index.md b/docs/index.md
index 19d3bb23870..1eb66f086fd 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,10 +1,32 @@
---
+layout: default
title: gRPC-Gateway
+nav_order: 1
+description: "Documentation site for the gRPC-Gateway"
+permalink: /
---
-# grpc-gateway
+# gRPC-Gateway
+{: .fs-9 }
-[](https://circleci.com/gh/grpc-ecosystem/grpc-gateway)
+gRPC-Gateway is a plugin of [protoc](https://github.com/protocolbuffers/protobuf).
+It reads a [gRPC](https://grpc.io) service definition,
+and generates a reverse-proxy server which translates a RESTful JSON API into gRPC.
+This server is generated according to [custom options](https://cloud.google.com/service-infrastructure/docs/service-management/reference/rpc/google.api#http) in your gRPC definition.
+{: .fs-6 .fw-300 }
+
+[Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [View it on GitHub](https://github.com/grpc-ecosystem/grpc-gateway){: .btn .fs-5 .mb-4 .mb-md-0 }
+
+---
+
+## About
+
+[](https://circleci.com/gh/grpc-ecosystem/grpc-gateway)
+[](https://codecov.io/gh/grpc-ecosystem/grpc-gateway)
+[](https://github.com/grpc-ecosystem/grpc-gateway/network/members)
+[](https://github.com/grpc-ecosystem/grpc-gateway/issues)
+[](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt)
+[](https://github.com/grpc-ecosystem/grpc-gateway/stargazers)
grpc-gateway is a plugin of [protoc](https://github.com/protocolbuffers/protobuf).
It reads a [gRPC](https://grpc.io) service definition,
@@ -15,19 +37,23 @@ It helps you to provide your APIs in both gRPC and RESTful style at the same tim
-To learn more about us check out our documentation on:
-
-- [Our background](_docs/background.md)
-- [Installation and usage](_docs/usage.md)
-- [Examples](_docs/examples.md)
-- [Features](_docs/features.md)
-- [AWS API Gateway tips](_docs/aws.md)
+To learn more about us check out our documentation.
-# Contribution
+## Contribution
See [CONTRIBUTING.md](http://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md).
-# License
+## License
grpc-gateway is licensed under the BSD 3-Clause License.
See [LICENSE.txt](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt) for more details.
+
+#### Thank you to the contributors of gRPC-Gateway!
+
+
+{% for contributor in site.github.contributors %}
+