grpc-gateway: a code generator that puts REST in front of your gRPC service

A protoc plugin, not a proxy you configure by hand

The description in the repository metadata says it plainly: gRPC to JSON proxy generator following the gRPC HTTP spec. The mechanism is code generation rather than runtime configuration. grpc-gateway is a plugin of protoc, it reads your protobuf service definitions, and it generates a reverse-proxy server that translates a RESTful HTTP API into gRPC. What tells it how to do that is the `google.api.http` annotation in your service definition, so the HTTP semantics live in the proto file next to the RPC signature rather than in a separate routing table.

That placement is the design decision that matters. A hand-written REST-to-gRPC shim means two descriptions of every endpoint, and they drift. Here there is one, and the generated proxy is checked in or built in CI like any other generated artefact.

The README is candid about why you would want it. gRPC generates clients and server stubs in many languages and is efficient, but a service may still need a traditional RESTful JSON API for backward compatibility, for languages with weak gRPC support, or simply because the HTTP and JSON tooling around REST is better developed. The project aims to supply that interface, and it says the configuration needed is small.

Installing four binaries into your GOBIN

The install path assumes Go Modules and pins the versions of the executables as tool dependencies. This README section is one of the better-written ones in the ecosystem, because it explains both the older and the current approach rather than assuming you already know what a tools.go file is.

The traditional pattern is a blank-import file so `go mod tidy` will not drop your generator binaries:

// +build tools

package tools

import (
    _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway"
    _ "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2"
    _ "google.golang.org/grpc/cmd/protoc-gen-go-grpc"
    _ "google.golang.org/protobuf/cmd/protoc-gen-go"
)

Then a single install command puts the four executables in your `$GOBIN`: `protoc-gen-grpc-gateway`, `protoc-gen-openapiv2`, `protoc-gen-go` and `protoc-gen-go-grpc`. protoc finds plugins by name on `$PATH`, so the README's reminder to check that `$GOBIN` is on it is not optional.

One detail to notice: the four binaries are two from this project and two from the protobuf and gRPC projects themselves. grpc-gateway cannot generate your Go service stubs, only the proxy that sits in front of them.

The Go 1.24 tool directive replaces the blank import file

For Go 1.24 and later, the README recommends the `tool` directive in go.mod and describes the blank-import pattern as mainly useful for projects not yet on 1.24. The go.mod file in the repository declares `go 1.26.0`, so the project has already moved.

The declaration looks like this:

module tools

go 1.24

tool (
	github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway
	github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2
	google.golang.org/grpc/cmd/protoc-gen-go-grpc
	google.golang.org/protobuf/cmd/protoc-gen-go
)

Tools are added with the `-tool` flag on `go get`, which records the tool and the require statement together so the version cannot drift:

go get -tool github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway
go get -tool github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2
go get -tool google.golang.org/protobuf/cmd/protoc-gen-go
go get -tool google.golang.org/grpc/cmd/protoc-gen-go-grpc

After that, `go install tool` installs everything in the directive. The practical upgrade benefit is that a `tools.go` file full of unused imports, which linters and IDEs routinely complain about, is no longer part of the tree.

Two OpenAPI generators, one of them explicitly alpha

The OpenAPI side has been the most interesting change in the project recently, and the README is unusually direct about its status. `protoc-gen-openapiv2` is described as the production-stable option, emitting Swagger 2.0. `protoc-gen-openapiv3` emits OpenAPI 3.1 instead, or in addition, and is labelled Alpha with a warning that its output is not yet stable: the emitted JSON shape for oneofs, wrappers, enums and similar constructs may change in response to real-world feedback before the plugin graduates.

That warning is worth reading literally. It says not to rely on the exact spec bytes being stable across minor releases, that the proto-to-OpenAPI mapping rules are likely to tighten, and that tooling-compatibility compromises documented in the generator source may be revisited. The README points at a separate documentation page for what the v3 generator supports and how it differs from v2.

Installing it is one line:

go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3

The release history backs the warning up. v2.30.0, published on 2026-08-05, introduced protoc-gen-openapiv3 as a minimal OpenAPI v3 generator, and the same release lists follow-up pull requests adding visibility selectors, a `disable_default_errors` option, annotation support, better plugin error surfacing, and `field_behavior REQUIRED` support for query parameters. A feature arriving with that many follow-ups in one release is a feature still finding its shape. The same release also added openapiv3-merge as a standalone tool for merging OpenAPI v3 documents.

What the example services and the Makefile reveal

The repository tests itself against a set of example protos rather than a toy single service, and the Makefile names them because they have shipped spec files checked in. The echo service is the baseline, a_bit_of_everything is the broad case that exercises most of the proto feature set, and there are dedicated ones for unannotated services, response bodies, and generating unbound methods.

That last set is the interesting design decision. An unannotated echo service spec exists, which means the project deliberately supports services with no `google.api.http` annotations at all, generating a gateway that follows default conventions rather than a mapped REST API. Whether you want that behaviour on or off is a policy question your API review should answer.

The Makefile also shows how the specs stay honest. For each example it runs swagger generate client against the checked-in spec, with a jq pass beforehand that rewrites string defaults on numeric and integer parameters into real numbers, because protoc-gen-openapiv2 emits a quoted zero on integer parameters and go-swagger refuses it. That is a small, specific workaround for a real interop gap between the two tools, and it is the kind of detail you only learn by reading the repository.

The bug history tells you which proto features are awkward

Recent releases are dominated by fixes at the edges of the proto type system, which is where a mapping generator earns its keep. v2.28.0 fixed a panic on enum resolution in nested messages and added an option to disable chunked headers. v2.29.0 allowed proto3 optional fields in path parameters, added an option to disable the HTTP method override, deprecated fields and methods when the file is deprecated, and switched to `proto.Merge` to avoid copylocks when `use_opaque_api=true`.

Read together, those are a list of places where HTTP and protobuf do not line up cleanly. An optional field inside a path segment has no obvious mapping, since a path cannot be null. Enums nested inside messages broke resolution. The HTTP method override is a gRPC convention with no REST analogue, so it needed a switch to turn off.

The dependency list in go.mod is also worth a look if you are auditing supply chain exposure. Beyond the protobuf and gRPC modules, the runtime pulls in go-openapi packages for validation and errors, oapi-codegen runtime, a YAML library, golang.org/x/text, and OpenTelemetry instrumentation for both gRPC and net/http, plus an OTLP-style stdout exporter and SDK. Observability hooks are compiled in rather than bolted on later, which is a design choice with a cost: the dependency surface is wide even if you never export a trace.

Editorial conclusion

grpc-gateway is the right tool when one service has to answer both gRPC clients and ordinary HTTP callers, and the wrong one when you are still deciding the shape of the API, because the HTTP mapping you annotate now is the HTTP contract you keep later. Start with the google.api.http annotations on a single unary method, install only protoc-gen-grpc-gateway and protoc-gen-openapiv2, and treat protoc-gen-openapiv3 as experimental, exactly as the README does. The go.mod in the repository now requires Go 1.26.0, so the version floor is worth checking against your own toolchain before you wire it into a build.

Frequently asked questions

Official sources

1. grpc-ecosystem/grpc-gateway on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases