Using runtime.WithMarshalerOption() breaks swagger docs

[VinGarcia]

🐛 Bug Report

I wanted to use snake_case on the JSON input and output of my grpc-gateway since this is how my company described the API I am writing.

So since the gateway generated json names automatically in camelCase I tried using the runtime.WithMarshalerOption() (in golang) to change this behavior like this:

	gw := runtime.NewServeMux(
		// ... other opts ...

		// Configure proxy to output camel_case json and to not omit
		// 0 values, such as 0, "" or null
		runtime.WithMarshalerOption(
			runtime.MIMEWildcard,
			&runtime.JSONPb{MarshalOptions: protojson.MarshalOptions{
				UseProtoNames:   true,
			}},
		),
	)

This worked since the proto names I am using are in snake_case, however, when I open the generated swagger documentation it still describes the input and output JSON as if all attributes used camelCase, and I was unable to find an option for fixing this.

So now it seems I will have to stop using this option in favor of naming the JSON name for each attribute on my proto file.

To Reproduce

In an existing grpc-gateway that automatically generates swagger docs add the option mentioned on the call to NewServeMux.

This will make the API read and respond using the proto names as attributes.

But will not update the swagger docs accordingly.

Expected behavior

I expected the swagger docs to show the responses with the actual values they are being generated by the code, e.g.:

(response JSON)

{
  "api_token": "string",
  "api_secret": "string",
}

Actual Behavior

Swagger is showing JSON inputs and outputs with attribute names written in camelCase, e.g.:

(response JSON)

{
  "apiToken": "string",
  "apiSecret": "string",
}

Your Environment

Golang version:

$ go version
go version go1.15.5 linux/amd64

Linux Distro:

$ uname -a
Linux vingarcia 5.8.18-1-MANJARO #1 SMP PREEMPT Sun Nov 1 14:10:04 UTC 2020 x86_64 GNU/Linux

Protoc download link (with version):

• https://github.com/protocolbuffers/protobuf/releases/download/v3.14.0/protoc-3.14.0-linux-x86_64.zip

grpc-gateway downloaded with:

go get -u \
    github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway \
    github.com/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv2

[johanbrandhorst]

Hi @VinGarcia, thanks for your bug report. It's your lucky day because we have an option that switches the behaviour of the openapiv2 generator already: see https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-openapiv2/main.go#L24. See also our v2 migration docs: https://grpc-ecosystem.github.io/grpc-gateway/docs/development/grpc-gateway_v2_migration_guide/#we-now-use-the-camelcase-json-names-by-default. I hope that helps, let me know if this doesn't solve your issue!

[VinGarcia]

Thanks @johanbrandhorst that's great, I didn't knew you had docs 😓

I just went looking on the README.md raw file for this link and I noticed it is not easy to find, maybe you could add a section ### See our docs or something like that.

Thanks again!

[johanbrandhorst]

If you couldn't see it, that means we didn't make it clear enough - I'd be very grateful if you could contribute a quick link somewhere you think you would've noticed it better. For this use case in particular (which is quite common), we might benefit from a dedicated customizing your gateway section too, if you had the time 😄. Thank you!

[VinGarcia]

Ok, I'll see what I can do, I will try to create a PR today if I have the time.

[VinGarcia]

@johanbrandhorst I just created the PR #1884, it is very short, but I believe it will help more people to find those docs.

[VinGarcia]

I didn't create a section about "Customizing your gateway" mostly because I am still learning so I don't feel qualified to write this section.