grpc-gateway

gRPC-Gateway is a protoc plugin that reads your protobuf service definitions and generates a reverse-proxy server translating a RESTful HTTP+JSON API into gRPC calls. It's aimed at Go developers who already have (or are building) a gRPC service and need to expose it over HTTP without hand-writing a separate REST layer.

The project targets teams that want to keep gRPC as the source of truth for their API contract while still serving clients that expect JSON over HTTP, such as browsers, mobile apps, or third-party integrations that don't support gRPC well.

Key features

• Reverse-proxy generation: reads google.api.http annotations in .proto files and generates Go server code that translates HTTP+JSON requests into gRPC calls.
• Default mapping mode: generate_unbound_methods lets you generate a working proxy without modifying .proto files at all, using default HTTP semantics.
• Custom HTTP mapping: attach google.api.http options to RPC methods to control paths, HTTP verbs, and body mapping.
• External configuration option: use a separate gRPC Service Configuration YAML file to map HTTP routes without touching proto files you don't control, useful with standalone=true.
• OpenAPI/Swagger generation: protoc-gen-openapiv2 produces Swagger 2.0 definitions from the same proto annotations, kept in sync with the gRPC contract.
• OpenAPI 3.1 support: protoc-gen-openapiv3 emits OpenAPI 3.1 output (marked alpha, output shape may change) as an alternative to the stable v2 plugin.
• Works with buf or protoc: generation is compatible with both the buf toolchain and raw protoc invocations.
• Signed release binaries: releases include SLSA3 provenance attestations that can be verified with slsa-verifier.

Ideal use cases

• You're building a gRPC service in Go and need a REST/JSON API for browser clients, mobile apps, or partners that can't use gRPC directly.
• You want a single proto definition to drive both your gRPC contract and your OpenAPI/Swagger documentation, avoiding drift between the two.
• You maintain a public API that needs backward compatibility with existing REST/JSON consumers while your internal services communicate over gRPC.
• You need to expose a gRPC service defined in a proto file you don't control (e.g., from another team or a third-party repo), using the external configuration option instead of editing the source proto.

It's not a good fit if you don't already use protobuf/gRPC for your service definitions, since it doesn't help you author a REST API from scratch. It also isn't useful if your clients can consume gRPC directly (e.g., internal service-to-service calls), where a gateway just adds overhead. And if you need fine-grained REST semantics that diverge significantly from your gRPC method structure, hand-writing the HTTP layer may be simpler than fighting the annotation model.

Installation

gRPC-Gateway is a Go project distributed as protoc plugins. Install the required tools with Go modules:

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

Make sure $GOBIN is on your $PATH. On Go 1.24+, you can track these as tool dependencies directly in go.mod:

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
)

Then install them with:

go install tool

After installing the plugins, the general workflow is:

1. Define your gRPC service in a .proto file.
2. Generate gRPC stubs with protoc-gen-go and protoc-gen-go-grpc (via buf generate or protoc).
3. Implement the gRPC service in Go as usual.
4. Run protoc-gen-grpc-gateway (with generate_unbound_methods, google.api.http annotations, or an external config file) to generate the reverse-proxy code.
5. Write a small Go entrypoint that registers the generated handler with runtime.NewServeMux() and serves it with http.ListenAndServe.
6. Optionally run protoc-gen-openapiv2 (or the alpha protoc-gen-openapiv3) to generate OpenAPI documentation from the same proto definitions.

Pre-built release binaries are also available on the GitHub releases page, with SLSA3 provenance files for verification via slsa-verifier.