gRPC-Gateway

gRPC to JSON proxy generator following the gRPC HTTP spec

About

The gRPC-Gateway is a plugin of the Google protocol buffers compiler protoc. It reads protobuf service definitions and generates a reverse-proxy server which translates a RESTful HTTP API into gRPC. This server is generated according to the google.api.http annotations in your service definitions.

This helps you provide your APIs in both gRPC and RESTful style at the same time.

Docs

You can read our docs at:

• https://grpc-ecosystem.github.io/grpc-gateway/

Testimonials

We use the gRPC-Gateway to serve millions of API requests per day, and have been since 2018 and through all of that, we have never had any issues with it.

- William Mill, Ad Hoc

Background

gRPC is great -- it generates API clients and server stubs in many programming languages, it is fast, easy-to-use, bandwidth-efficient and its design is combat-proven by Google. However, you might still want to provide a traditional RESTful JSON API as well. Reasons can range from maintaining backward-compatibility, supporting languages or clients that are not well supported by gRPC, to simply maintaining the aesthetics and tooling involved with a RESTful JSON architecture.

This project aims to provide that HTTP+JSON interface to your gRPC service. A small amount of configuration in your service to attach HTTP semantics is all that's needed to generate a reverse-proxy with this library.

Installation

Compile from source

The following instructions assume you are using Go Modules for dependency management. Use a tool dependency to track the versions of the following executable packages:

For Go 1.24 and later, prefer the tool directive in go.mod described in the "Tracking Tools in go.mod" section. The following blank-import pattern is mainly useful for projects that are not using Go 1.24 yet.

// +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"
)

Run go mod tidy to resolve the versions. Install by running

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

This will place four binaries in your $GOBIN;

• protoc-gen-grpc-gateway
• protoc-gen-openapiv2
• protoc-gen-go
• protoc-gen-go-grpc

Make sure that your $GOBIN is in your $PATH.

If you want to emit OpenAPI 3.1 instead of (or in addition to) Swagger 2.0, install protoc-gen-openapiv3 as well:

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

⚠️ Alpha. protoc-gen-openapiv3 is new and 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. Don't rely on the exact spec bytes being stable across minor releases; the proto-to-OpenAPI mapping rules are likely to tighten, and tooling-compatibility compromises (documented in the generator source) may be revisited as consumer OpenAPI 3.1 support matures. protoc-gen-openapiv2 is the production-stable option.

See OpenAPI 3.1 Output for what it supports and how it differs from protoc-gen-openapiv2.

Using the tool Directive in Go 1.24

Starting from Go 1.24, the tool directive in go.mod provides a structured way to track and manage executable dependencies. This replaces the previous workaround of using a separate tools.go file with blank imports.

Tracking Tools in go.mod

Instead of manually importing tool dependencies in a Go source file, you can now use the tool directive in go.mod to declare the tools your project depends on. For example:

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
)

Managing Tool Dependencies

To add tools to your module, use the -tool flag with go get:

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

This automatically updates go.mod, adding the tools under the tool directive along with require statements to ensure version tracking.

Install Tools

Once the tool dependencies are properly recorded in the go.mod file, simply execute the following command in the root directory of your project:

go install tool

This will place four binaries in your $GOBIN;

• protoc-gen-grpc-gateway
• protoc-gen-openapiv2
• protoc-gen-go
• protoc-gen-go-grpc

Make sure that your $GOBIN is in your $PATH.

Download the binaries

You may alternatively download the binaries from the GitHub releases page. We generate SLSA3 signatures using the OpenSSF's slsa-framework/slsa-github-generator during the release process. To verify a release binary:

1. Install the verification tool from slsa-framework/slsa-verifier#installation.
2. Download the provenance file attestation.intoto.jsonl from the GitHub releases page.
3. Run the verifier:

slsa-verifier -artifact-path <the-binary> -provenance attestation.intoto.jsonl -source github.com/grpc-ecosystem/grpc-gateway -tag <the-tag>

Alternatively, see the section on remotely managed plugin versions below.

Usage

1.Define your gRPC service using protocol buffers

your_service.proto:

 syntax = "proto3";
 package your.service.v1;
 option go_package = "github.com/yourorg/yourprotos/gen/go/your/service/v1";

 message StringMessage {
   string value = 1;
 }

 service YourService {
   rpc Echo(StringMessage) returns (StringMessage) {}
 }

2. Generate gRPC stubs

This step generates the gRPC stubs that you can use to implement the service and consume from clients:

Here's an example buf.gen.yaml you can use to generate the stubs with buf:

version: v2
plugins:
  - local: protoc-gen-go
    out: gen/go
    opt:
      - paths=source_relative
  - local: protoc-gen-go-grpc
    out: gen/go
    opt:
      - paths=source_relative

With this file in place, you can generate your files using buf generate.

For a complete example of using buf generate to generate protobuf stubs, see [the boilerplate repo](https