Skip to content

Commit cdf2846

Browse files
johanbrandhorstjohanbrandhorst
committed
Update docs for v2
1 parent 75b67e3 commit cdf2846

File tree

3 files changed

+144
-60
lines changed

3 files changed

+144
-60
lines changed

‎docs/_docs/customizingyourgateway.md

Lines changed: 28 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,21 @@ You might want to serialize request/response messages in MessagePack instead of
2323

2424
You can see [the default implementation for JSON](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/runtime/marshal_jsonpb.go) for reference.
2525

26-
### Using camelCase for JSON
26+
### Using proto names in JSON
2727

28-
The protocol buffer compiler generates camelCase JSON tags that can be used with jsonpb package. By default jsonpb Marshaller uses `OrigName: true` which uses the exact case used in the proto files. To use camelCase for the JSON representation,
28+
The protocol buffer compiler generates camelCase JSON tags that are used by default.
29+
If you want to use the exact case used in the proto files, set `UseProtoNames: true`:
2930
```go
30-
mux := runtime.NewServeMux(runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{OrigName:false}))
31+
mux := runtime.NewServeMux(
32+
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{
33+
MarshalOptions: protojson.MarshalOptions{
34+
UseProtoNames: true,
35+
},
36+
UnmarshalOptions: protojson.UnmarshalOptions{
37+
DiscardUnknown: true,
38+
},
39+
}),
40+
)
3141
```
3242

3343
### Pretty-print JSON responses when queried with ?pretty
@@ -42,7 +52,15 @@ For example:
4252

4353
```go
4454
mux := runtime.NewServeMux(
45-
runtime.WithMarshalerOption("application/json+pretty", &runtime.JSONPb{Indent: " "}),
55+
runtime.WithMarshalerOption("application/json+pretty", &runtime.JSONPb{
56+
MarshalOptions: protojson.MarshalOptions{
57+
Indent: " ",
58+
Multiline: true, // Optional, implied by presence of "Indent".
59+
},
60+
UnmarshalOptions: protojson.UnmarshalOptions{
61+
DiscardUnknown: true,
62+
},
63+
}),
4664
)
4765
prettier := func(h http.Handler) http.Handler {
4866
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -57,22 +75,6 @@ prettier := func(h http.Handler) http.Handler {
5775
http.ListenAndServe(":8080", prettier(mux))
5876
```
5977

60-
Note that `runtime.JSONPb{Indent: " "}` will do the trick for pretty-printing: it wraps
61-
`jsonpb.Marshaler`:
62-
```go
63-
type Marshaler struct {
64-
// ...
65-
66-
// A string to indent each level by. The presence of this field will
67-
// also cause a space to appear between the field separator and
68-
// value, and for newlines to appear between fields and array
69-
// elements.
70-
Indent string
71-
72-
// ...
73-
}
74-
```
75-
7678
Now, either when passing the header `Accept: application/json+pretty` or appending `?pretty` to
7779
your HTTP endpoints, the response will be pretty-printed.
7880

@@ -81,42 +83,15 @@ also, this example code does not remove the query parameter `pretty` from furthe
8183

8284
## Customize unmarshaling per Content-Type
8385

84-
Having different unmarshaling options per Content-Type is possible by wrapping the decoder and passing that to `runtime.WithMarshalerOption`:
85-
86-
```go
87-
type m struct {
88-
*runtime.JSONPb
89-
unmarshaler *jsonpb.Unmarshaler
90-
}
91-
92-
type decoderWrapper struct {
93-
*json.Decoder
94-
*jsonpb.Unmarshaler
95-
}
96-
97-
func (n *m) NewDecoder(r io.Reader) runtime.Decoder {
98-
d := json.NewDecoder(r)
99-
return &decoderWrapper{Decoder: d, Unmarshaler: n.unmarshaler}
100-
}
101-
102-
func (d *decoderWrapper) Decode(v interface{}) error {
103-
p, ok := v.(proto.Message)
104-
if !ok { // if it's not decoding into a proto.Message, there's no notion of unknown fields
105-
return d.Decoder.Decode(v)
106-
}
107-
return d.UnmarshalNext(d.Decoder, p) // uses m's jsonpb.Unmarshaler configuration
108-
}
109-
```
110-
111-
This scaffolding allows us to pass a custom unmarshal options. In this example, we configure the
112-
unmarshaler to disallow unknown fields. For demonstration purposes, we'll also change some of the
113-
default marshaler options:
86+
Having different unmarshaling options per Content-Type is as easy as
87+
configuring a custom marshaler:
11488

11589
```go
11690
mux := runtime.NewServeMux(
117-
runtime.WithMarshalerOption("application/json+strict", &m{
118-
JSONPb: &runtime.JSONPb{EmitDefaults: true},
119-
unmarshaler: &jsonpb.Unmarshaler{AllowUnknownFields: false}, // explicit "false", &jsonpb.Unmarshaler{} would have the same effect
91+
runtime.WithMarshalerOption("application/json+strict", &runtime.JSONPb{
92+
UnmarshalOptions: &protojson.UnmarshalOptions{
93+
DiscardUnknown: false, // explicit "false", &protojson.UnmarshalOptions{} would have the same effect
94+
},
12095
}),
12196
)
12297
```

‎docs/_docs/httpbody.md

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,7 @@ category: documentation
66
The [HTTP Body](https://github.com/googleapis/googleapis/blob/master/google/api/httpbody.proto) messages allows a response message to be specified with custom data content and a custom content type header. The values included in the HTTPBody response will be used verbatim in the returned message from the gateway. Make sure you format your response carefully!
77

88
## Example Usage
9-
1. Create a mux and configure it to use the `HTTPBodyMarshaler`.
10-
11-
```protobuf
12-
mux := runtime.NewServeMux()
13-
runtime.SetHTTPBodyMarshaler(mux)
14-
```
15-
2. Define your service in gRPC with an httpbody response message
9+
1. Define your service in gRPC with an httpbody response message
1610

1711
```protobuf
1812
import "google/api/httpbody.proto";

‎docs/_docs/v2-migration.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: v2 migration guide
3+
category: documentation
4+
---
5+
6+
# gRPC-Gateway v2 migration guide
7+
8+
This guide is supposed to help users of the gateway migrate from v1 to v2.
9+
See https://github.com/grpc-ecosystem/grpc-gateway/issues/1223 for detailed
10+
information on all changes that were made specifically to v2.
11+
12+
The following behavioural defaults have been changed:
13+
14+
## We now use the camelCase JSON names by default
15+
See
16+
[the original issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/375)
17+
and
18+
[original pull request](https://github.com/grpc-ecosystem/grpc-gateway/issues/375)
19+
for more information.
20+
21+
If you want to revert to the old behaviour, configure a custom marshaler with
22+
`UseProtoNames: true`:
23+
```go
24+
mux := runtime.NewServeMux(
25+
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{
26+
MarshalOptions: protojson.MarshalOptions{
27+
UseProtoNames: true,
28+
},
29+
UnmarshalOptions: protojson.UnmarshalOptions{
30+
DiscardUnknown: true,
31+
},
32+
}),
33+
)
34+
```
35+
36+
To change the swagger generator behaviour to match, set `json_names_for_fields=false` when generating:
37+
38+
```shell
39+
--swagger_out=json_names_for_fields=false:./gen/swagger path/to/my/proto/v1/myproto.proto
40+
```
41+
42+
## We now emit default vaules for all fields
43+
44+
See [the original issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/233)
45+
for more information.
46+
47+
If you want to revert to the old behaviour, configure a custom marshaler with
48+
`EmitUnpopulated: false`:
49+
```go
50+
mux := runtime.NewServeMux(
51+
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{
52+
MarshalOptions: protojson.MarshalOptions{
53+
EmitUnpopulated: false,
54+
},
55+
UnmarshalOptions: protojson.UnmarshalOptions{
56+
DiscardUnknown: true,
57+
},
58+
}),
59+
)
60+
```
61+
62+
## We now support google.api.HttpBody message types by default
63+
64+
The `runtime.SetHTTPBodyMarshaler` function has disappeared, and is now
65+
enabled by default. If you for some reason don't want `HttpBody` messages to be
66+
respected, you can disable it by overwriting the default marshaler:
67+
68+
```go
69+
mux := runtime.NewServeMux(
70+
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{
71+
MarshalOptions: protojson.MarshalOptions{
72+
EmitUnpopulated: true,
73+
},
74+
UnmarshalOptions: protojson.UnmarshalOptions{
75+
DiscardUnknown: true,
76+
},
77+
}),
78+
)
79+
```
80+
81+
## runtime.DisallowUnknownFields has been removed
82+
83+
All marshalling settings are now inherited from the configured marshaler. If you wish
84+
to disallow unknown fields, configure a custom marshaler:
85+
86+
```go
87+
mux := runtime.NewServeMux(
88+
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{
89+
MarshalOptions: protojson.MarshalOptions{
90+
EmitUnpopulated: true,
91+
},
92+
UnmarshalOptions: protojson.UnmarshalOptions{
93+
DiscardUnknown: false,
94+
},
95+
}),
96+
)
97+
```
98+
99+
## WithLastMatchWins and allow_colon_final_segments=true is now default behaviour
100+
101+
If you were previously specifying these, please remove them, as this is now
102+
the default behaviour. See
103+
[the original issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/224)
104+
for more information.
105+
106+
There is no workaround for this, as we considered it a correct interpretation of the spec.
107+
If this breaks your application, carefully consider the order in which you define your
108+
services.
109+
110+
## Error handling configuration has been overhauled
111+
112+
`runtime.HTTPError`, `runtime.OtherErrorHandler`, `runtime.GlobalHTTPErrorHandler`,
113+
`runtime.WithProtoErrorHandler` are all gone. Error handling is rewritten around the
114+
use of gRPCs Status types. If you wish to configure how the gateway handles errors,
115+
please use `runtime.WithErrorHandler` and `runtime.WithStreamErrorHandler`.

0 commit comments

Comments
 (0)