Repolode
Submit
grpc-ecosystem

grpc-ecosystem/grpc-gateway

A protoc plugin that generates a reverse-proxy server translating RESTful JSON HTTP calls into gRPC requests for Go services.

View on GitHubWebsite
Stars
20,008
Forks
2,415
Open issues
150
Last commit
16 hours ago

What is it?

gRPC-Gateway is a plugin for the Protocol Buffers compiler (protoc) that reads protobuf service definitions and generates a reverse-proxy server. The server accepts RESTful HTTP+JSON requests and forwards them to your gRPC service, so one implementation can serve both gRPC and JSON clients.

The HTTP mapping is driven by google.api.http annotations in the .proto file. Without any annotations, the generator can still expose methods using a default mapping, and an external gRPC API Configuration file can supply HTTP rules when the proto files cannot be modified. The project also includes protoc-gen-openapiv2 for Swagger 2.0 definitions, and an alpha protoc-gen-openapiv3 for OpenAPI 3.1 output.

The generated code depends on the grpc-gateway runtime package for Go. It supports query string and path parameters, PATCH requests mapped to field masks, streaming responses as newline-delimited JSON, and gRPC timeouts set via the Grpc-Timeout header.

Key features

  • 01Generates a reverse-proxy that translates HTTP+JSON requests into gRPC calls.
  • 02Maps HTTP paths, query parameters and request bodies to gRPC messages via google.api.http annotations.
  • 03Generates Swagger 2.0 definitions with protoc-gen-openapiv2.
  • 04Offers an alpha OpenAPI 3.1 generator, protoc-gen-openapiv3.
  • 05Translates PATCH requests into field mask gRPC requests and streams responses as newline-delimited JSON.

Use cases

  • Exposing an existing gRPC service to clients that only speak JSON over REST.
  • Keeping a RESTful API for backward compatibility while adding gRPC internally.
  • Generating Swagger or OpenAPI documentation directly from protobuf definitions.
  • Serving a gRPC backend to browsers or languages with weak gRPC support.

Quick start

  1. 1

    Install the gateway plugin with Go

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

    Write your gRPC service in a .proto file with google.api.http annotations

  3. 3

    Generate the reverse-proxy code with protoc or buf using the plugin

    protoc -I . --grpc-gateway_out ./gen/go --grpc-gateway_opt paths=source_relative your/service/v1/your_service.proto

Things to know

  • Only generates Go code, for Go services.
  • Requires protoc or buf and protobuf toolchain setup to generate code.
  • The OpenAPI 3.1 generator (protoc-gen-openapiv3) is alpha and its output may change.

In collections

Microservice frameworks & service infrastructure

Topics

#grpc#rest-api#protobuf#go#openapi#swagger#reverse-proxy#code-generation#grpc-gateway#restful-api

FAQ

What is grpc-gateway?
A protoc plugin that generates a reverse-proxy server translating RESTful JSON HTTP calls into gRPC requests for Go services. gRPC-Gateway is a plugin for the Protocol Buffers compiler (protoc) that reads protobuf service definitions and generates a reverse-proxy server. The server accepts RESTful HTTP+JSON requests and forwards them to your gRPC service, so one implementation can serve both gRPC and JSON clients.
Is grpc-gateway free to use? What license does it have?
grpc-gateway is open source under the BSD-3-Clause license. Check the license terms before using it in commercial products.
Is grpc-gateway still maintained?
Actively maintained. The last commit to grpc-gateway was on Oct 22, 2026.
What can I use grpc-gateway for?
Exposing an existing gRPC service to clients that only speak JSON over REST. Keeping a RESTful API for backward compatibility while adding gRPC internally. Generating Swagger or OpenAPI documentation directly from protobuf definitions. Serving a gRPC backend to browsers or languages with weak gRPC support.
How do I install grpc-gateway?
Install the gateway plugin with Go: go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway Write your gRPC service in a .proto file with google.api.http annotations Generate the reverse-proxy code with protoc or buf using the plugin: protoc -I . --grpc-gateway_out ./gen/go --grpc-gateway_opt paths=source_relative your/service/v1/your_service.proto
Where can I get grpc-gateway?
The source code and installation instructions are on GitHub: https://github.com/grpc-ecosystem/grpc-gateway

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects