[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-4817":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":24,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":32,"readmeContent":33,"aiSummary":34,"trendingCount":16,"starSnapshotCount":16,"syncStatus":35,"lastSyncTime":36,"discoverSource":37},4817,"grpc-gateway","grpc-ecosystem\u002Fgrpc-gateway","grpc-ecosystem","gRPC to JSON proxy generator following the gRPC HTTP spec","https:\u002F\u002Fgrpc-ecosystem.github.io\u002Fgrpc-gateway\u002F",null,"Go",19915,2379,268,143,0,9,34,4,77.9,"BSD 3-Clause \"New\" or \"Revised\" License",false,"main",true,[26,27,5,28,29,30,31],"go","grpc","openapi","rest-api","restful-api","swagger","2026-06-12 04:00:22","\u003Cdiv align=\"center\">\n\u003Ch1>gRPC-Gateway\u003C\u002Fh1>\n\u003Cp>\ngRPC to JSON proxy generator following the gRPC HTTP spec\n\u003C\u002Fp>\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fci.yml?color=379c9c&label=build&logo=github&logoColor=ffffff&style=flat-square\"\u002F>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fapp.slack.com\u002Fclient\u002FT029RQSE6\u002FCBATURP1D\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fslack-grpc--gateway-379c9c?logo=slack&logoColor=ffffff&style=flat-square\"\u002F>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fblob\u002Fmain\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fgrpc-ecosystem\u002Fgrpc-gateway?color=379c9c&style=flat-square\"\u002F>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fpkg.go.dev\u002Fgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fgodoc-reference-379c9c?style=flat-square&logo=go&logoColor=ffffff\"\u002F>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fgrpc-ecosystem\u002Fgrpc-gateway?color=379c9c&logoColor=ffffff&style=flat-square\"\u002F>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fgrpc-ecosystem\u002Fgrpc-gateway?color=379c9c&style=flat-square\"\u002F>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fslsa.dev\u002Fimages\u002Fgh-badge-level3.svg\">\u003Cimg src=\"https:\u002F\u002Fslsa.dev\u002Fimages\u002Fgh-badge-level3.svg\"\u002F>\u003C\u002Fa>\n\n\u003C\u002Fdiv>\n\n## About\n\nThe gRPC-Gateway is a plugin of the Google protocol buffers compiler\n[protoc](https:\u002F\u002Fgithub.com\u002Fprotocolbuffers\u002Fprotobuf).\nIt reads protobuf service definitions and generates a reverse-proxy server which\ntranslates a RESTful HTTP API into gRPC. This server is generated according to the\n[`google.api.http`](https:\u002F\u002Fgithub.com\u002Fgoogleapis\u002Fgoogleapis\u002Fblob\u002Fmaster\u002Fgoogle\u002Fapi\u002Fhttp.proto#L46)\nannotations in your service definitions.\n\nThis helps you provide your APIs in both gRPC and RESTful style at the same time.\n\n\u003Cdiv align=\"center\">\n\u003Cimg src=\"docs\u002Fassets\u002Fimages\u002Farchitecture_introduction_diagram.svg\" \u002F>\n\u003C\u002Fdiv>\n\n## Docs\n\nYou can read our docs at:\n\n- https:\u002F\u002Fgrpc-ecosystem.github.io\u002Fgrpc-gateway\u002F\n\n## Testimonials\n\n> We use the gRPC-Gateway to serve millions of API requests per day,\n> and have been since 2018 and through all of that,\n> we have never had any issues with it.\n>\n> _- William Mill, [Ad Hoc](http:\u002F\u002Fadhocteam.us\u002F)_\n\n## Background\n\ngRPC is great -- it generates API clients and server stubs in many programming\nlanguages, it is fast, easy-to-use, bandwidth-efficient and its design is\ncombat-proven by Google. However, you might still want to provide a traditional\nRESTful JSON API as well. Reasons can range from maintaining\nbackward-compatibility, supporting languages or clients that are not well supported by\ngRPC, to simply maintaining the aesthetics and tooling involved with a RESTful\nJSON architecture.\n\nThis project aims to provide that HTTP+JSON interface to your gRPC service.\nA small amount of configuration in your service to attach HTTP semantics is all\nthat's needed to generate a reverse-proxy with this library.\n\n## Installation\n\n### Compile from source\n\nThe following instructions assume you are using\n[Go Modules](https:\u002F\u002Fgo.dev\u002Fwiki\u002FModules) for dependency\nmanagement. Use a\n[tool dependency](https:\u002F\u002Fgo.dev\u002Fwiki\u002FModules#how-can-i-track-tool-dependencies-for-a-module)\nto track the versions of the following executable packages:\n\n```go\n\u002F\u002F +build tools\n\npackage tools\n\nimport (\n    _ \"github.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\u002Fprotoc-gen-grpc-gateway\"\n    _ \"github.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\u002Fprotoc-gen-openapiv2\"\n    _ \"google.golang.org\u002Fgrpc\u002Fcmd\u002Fprotoc-gen-go-grpc\"\n    _ \"google.golang.org\u002Fprotobuf\u002Fcmd\u002Fprotoc-gen-go\"\n)\n```\n\nRun `go mod tidy` to resolve the versions. Install by running\n\n```sh\ngo install \\\n    github.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\u002Fprotoc-gen-grpc-gateway \\\n    github.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\u002Fprotoc-gen-openapiv2 \\\n    google.golang.org\u002Fprotobuf\u002Fcmd\u002Fprotoc-gen-go \\\n    google.golang.org\u002Fgrpc\u002Fcmd\u002Fprotoc-gen-go-grpc\n```\n\nThis will place four binaries in your `$GOBIN`;\n\n- `protoc-gen-grpc-gateway`\n- `protoc-gen-openapiv2`\n- `protoc-gen-go`\n- `protoc-gen-go-grpc`\n\nMake sure that your `$GOBIN` is in your `$PATH`.\n\nIf you want to emit OpenAPI 3.1 instead of (or in addition to) Swagger 2.0,\ninstall `protoc-gen-openapiv3` as well:\n\n```sh\ngo install github.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\u002Fprotoc-gen-openapiv3\n```\n\n> ⚠️ **Alpha.** `protoc-gen-openapiv3` is new and its output is not yet\n> stable — the emitted JSON shape for oneofs, wrappers, enums, and similar\n> constructs may change in response to real-world feedback before the\n> plugin graduates. Don't rely on the exact spec bytes being stable across\n> minor releases; the proto-to-OpenAPI mapping rules are likely to\n> tighten, and tooling-compatibility compromises (documented in the\n> generator source) may be revisited as consumer OpenAPI 3.1 support\n> matures. `protoc-gen-openapiv2` is the production-stable option.\n\nSee [OpenAPI 3.1 Output](https:\u002F\u002Fgrpc-ecosystem.github.io\u002Fgrpc-gateway\u002Fdocs\u002Fmapping\u002Fopenapi_v3\u002F)\nfor what it supports and how it differs from `protoc-gen-openapiv2`.\n\n### **Using the `tool` Directive in Go 1.24**\n\nStarting 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.\n\n#### **Tracking Tools in `go.mod`**\n\nInstead 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:\n\n```go\nmodule tools\n\ngo 1.24\n\ntool (\n\tgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\u002Fprotoc-gen-grpc-gateway\n\tgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\u002Fprotoc-gen-openapiv2\n\tgoogle.golang.org\u002Fgrpc\u002Fcmd\u002Fprotoc-gen-go-grpc\n\tgoogle.golang.org\u002Fprotobuf\u002Fcmd\u002Fprotoc-gen-go\n)\n```\n\n#### **Managing Tool Dependencies**\n\nTo add tools to your module, use the `-tool` flag with `go get`:\n\n```sh\ngo get -tool github.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\u002Fprotoc-gen-grpc-gateway\ngo get -tool github.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\u002Fprotoc-gen-openapiv2\ngo get -tool google.golang.org\u002Fprotobuf\u002Fcmd\u002Fprotoc-gen-go\ngo get -tool google.golang.org\u002Fgrpc\u002Fcmd\u002Fprotoc-gen-go-grpc\n```\n\nThis automatically updates `go.mod`, adding the tools under the `tool` directive along with `require` statements to ensure version tracking.\n\n### Install Tools\n\nOnce the tool dependencies are properly recorded in the `go.mod` file, simply execute the following command in the root directory of your project:\n\n```sh\ngo install tool\n```\n\nThis will place four binaries in your `$GOBIN`;\n\n- `protoc-gen-grpc-gateway`\n- `protoc-gen-openapiv2`\n- `protoc-gen-go`\n- `protoc-gen-go-grpc`\n\nMake sure that your `$GOBIN` is in your `$PATH`.\n\n### Download the binaries\n\nYou may alternatively download the binaries from the [GitHub releases page](https:\u002F\u002Fgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Freleases\u002Flatest).\nWe generate [SLSA3 signatures](slsa.dev) using the OpenSSF's [slsa-framework\u002Fslsa-github-generator](https:\u002F\u002Fgithub.com\u002Fslsa-framework\u002Fslsa-github-generator) during the release process. To verify a release binary:\n\n1. Install the verification tool from [slsa-framework\u002Fslsa-verifier#installation](https:\u002F\u002Fgithub.com\u002Fslsa-framework\u002Fslsa-verifier#installation).\n2. Download the provenance file `attestation.intoto.jsonl` from the [GitHub releases page](https:\u002F\u002Fgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Freleases\u002Flatest).\n3. Run the verifier:\n\n```shell\nslsa-verifier -artifact-path \u003Cthe-binary> -provenance attestation.intoto.jsonl -source github.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway -tag \u003Cthe-tag>\n```\n\nAlternatively, see the section on remotely managed plugin versions below.\n\n## Usage\n\n### 1.Define your [gRPC](https:\u002F\u002Fgrpc.io\u002Fdocs\u002F) service using protocol buffers\n\n`your_service.proto`:\n\n```protobuf\n syntax = \"proto3\";\n package your.service.v1;\n option go_package = \"github.com\u002Fyourorg\u002Fyourprotos\u002Fgen\u002Fgo\u002Fyour\u002Fservice\u002Fv1\";\n\n message StringMessage {\n   string value = 1;\n }\n\n service YourService {\n   rpc Echo(StringMessage) returns (StringMessage) {}\n }\n```\n\n### 2. Generate gRPC stubs\n\nThis step generates the gRPC stubs that you can use to implement the service and consume from clients:\n\nHere's an example `buf.gen.yaml` you can use to generate the stubs with [buf](https:\u002F\u002Fgithub.com\u002Fbufbuild\u002Fbuf):\n\n```yaml\nversion: v2\nplugins:\n  - local: protoc-gen-go\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - local: protoc-gen-go-grpc\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n```\n\nWith this file in place, you can generate your files using `buf generate`.\n\n> For a complete example of using `buf generate` to generate protobuf stubs, see\n> [the boilerplate repo](https:\u002F\u002Fgithub.com\u002Fjohanbrandhorst\u002Fgrpc-gateway-boilerplate).\n> For more information on generating the stubs with buf, see\n> [the official documentation](https:\u002F\u002Fdocs.buf.build\u002Fgenerate-usage).\n\nIf you are using `protoc` to generate stubs, here's an example of what a command\nmight look like:\n\n```sh\nprotoc -I . \\\n    --go_out .\u002Fgen\u002Fgo\u002F --go_opt paths=source_relative \\\n    --go-grpc_out .\u002Fgen\u002Fgo\u002F --go-grpc_opt paths=source_relative \\\n    your\u002Fservice\u002Fv1\u002Fyour_service.proto\n```\n\n### 3. Implement your service in gRPC as usual.\n\n### 4. Generate reverse-proxy using `protoc-gen-grpc-gateway`\n\nAt this point, you have 3 options:\n\n- no further modifications, use the default mapping to HTTP semantics (method, path, etc.)\n  - this will work on any `.proto` file, but will not allow setting HTTP paths, request parameters or similar\n- additional `.proto` modifications to use a custom mapping\n  - relies on parameters in the `.proto` file to set custom HTTP mappings\n- no `.proto` modifications, but use an external configuration file\n  - relies on an external configuration file to set custom HTTP mappings\n  - mostly useful when the source proto file isn't under your control\n\n#### 1. Using the default mapping\n\nThis requires no additional modification to the `.proto` file but does require enabling a specific option when executing the plugin.\nThe `generate_unbound_methods` should be enabled.\n\nHere's what a `buf.gen.yaml` file might look like with this option enabled:\n\n```yaml\nversion: v2\nplugins:\n  - local: protoc-gen-go\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - local: protoc-gen-go-grpc\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - local: protoc-gen-grpc-gateway\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n      - generate_unbound_methods=true\n```\n\nWith `protoc` (just the grpc-gateway stubs):\n\n```sh\nprotoc -I . --grpc-gateway_out .\u002Fgen\u002Fgo \\\n    --grpc-gateway_opt paths=source_relative \\\n    --grpc-gateway_opt generate_unbound_methods=true \\\n    your\u002Fservice\u002Fv1\u002Fyour_service.proto\n```\n\n#### 2. With custom annotations\n\nAdd a [`google.api.http`](https:\u002F\u002Fgithub.com\u002Fgoogleapis\u002Fgoogleapis\u002Fblob\u002Fmaster\u002Fgoogle\u002Fapi\u002Fhttp.proto#L46)\nannotation to your .proto file\n\n`your_service.proto`:\n\n```diff\n syntax = \"proto3\";\n package your.service.v1;\n option go_package = \"github.com\u002Fyourorg\u002Fyourprotos\u002Fgen\u002Fgo\u002Fyour\u002Fservice\u002Fv1\";\n+\n+import \"google\u002Fapi\u002Fannotations.proto\";\n+\n message StringMessage {\n   string value = 1;\n }\n\n service YourService {\n-  rpc Echo(StringMessage) returns (StringMessage) {}\n+  rpc Echo(StringMessage) returns (StringMessage) {\n+    option (google.api.http) = {\n+      post: \"\u002Fv1\u002Fexample\u002Fecho\"\n+      body: \"*\"\n+    };\n+  }\n }\n```\n\n> You will need to provide the required third party protobuf files to the protobuf compiler.\n> If you are using [buf](https:\u002F\u002Fgithub.com\u002Fbufbuild\u002Fbuf), this dependency can\n> be added to the `deps` array in your `buf.yaml` under the name\n> `buf.build\u002Fgoogleapis\u002Fgoogleapis`:\n>\n> ```yaml\n> version: v2\n> name: buf.build\u002Fyourorg\u002Fmyprotos\n> deps:\n>   - buf.build\u002Fgoogleapis\u002Fgoogleapis\n> ```\n>\n> Always run `buf dep update` after adding a dependency to your `buf.yaml`.\n\nSee [a_bit_of_everything.proto](examples\u002Finternal\u002Fproto\u002Fexamplepb\u002Fa_bit_of_everything.proto)\nfor examples of more annotations you can add to customize gateway behavior\nand generated OpenAPI output.\n\nHere's what a `buf.gen.yaml` file might look like:\n\n```yaml\nversion: v2\nplugins:\n  - local: protoc-gen-go\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - local: protoc-gen-go-grpc\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - local: protoc-gen-grpc-gateway\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n```\n\nIf you are using `protoc` to generate stubs, you need to ensure the required\ndependencies are available to the compiler at compile time. These can be found\nby manually cloning and copying the relevant files from the\n[googleapis repository](https:\u002F\u002Fgithub.com\u002Fgoogleapis\u002Fgoogleapis), and providing\nthem to `protoc` when running. The files you will need are:\n\n```\ngoogle\u002Fapi\u002Fannotations.proto\ngoogle\u002Fapi\u002Ffield_behavior.proto\ngoogle\u002Fapi\u002Fhttp.proto\ngoogle\u002Fapi\u002Fhttpbody.proto\n```\n\nHere's what a `protoc` execution might look like:\n\n```sh\nprotoc -I . --grpc-gateway_out .\u002Fgen\u002Fgo \\\n    --grpc-gateway_opt paths=source_relative \\\n    your\u002Fservice\u002Fv1\u002Fyour_service.proto\n```\n\n#### 3. External configuration\n\nIf you do not want to (or cannot) modify the proto file for use with gRPC-Gateway you can\nalternatively use an external\n[gRPC Service Configuration](https:\u002F\u002Fcloud.google.com\u002Fendpoints\u002Fdocs\u002Fgrpc\u002Fgrpc-service-config) file.\n[Check our documentation](https:\u002F\u002Fgrpc-ecosystem.github.io\u002Fgrpc-gateway\u002Fdocs\u002Fmapping\u002Fgrpc_api_configuration\u002F)\nfor more information. This is best combined with the `standalone=true` option\nto generate a file that can live in its own package, separate from the files\ngenerated by the source protobuf file.\n\nHere's what a `buf.gen.yaml` file might look like with this option enabled:\n\n```yaml\nversion: v2\nplugins:\n  - local: protoc-gen-go\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - local: protoc-gen-go-grpc\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - local: protoc-gen-grpc-gateway\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n      - grpc_api_configuration=path\u002Fto\u002Fconfig.yaml\n      - standalone=true\n```\n\nWith `protoc` (just the grpc-gateway stubs):\n\n```sh\nprotoc -I . --grpc-gateway_out .\u002Fgen\u002Fgo \\\n    --grpc-gateway_opt paths=source_relative \\\n    --grpc-gateway_opt grpc_api_configuration=path\u002Fto\u002Fconfig.yaml \\\n    --grpc-gateway_opt standalone=true \\\n    your\u002Fservice\u002Fv1\u002Fyour_service.proto\n```\n\n### 5. Write an entrypoint for the HTTP reverse-proxy server\n\n```go\npackage main\n\nimport (\n  \"context\"\n  \"flag\"\n  \"net\u002Fhttp\"\n\n  \"github.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2\u002Fruntime\"\n  \"google.golang.org\u002Fgrpc\"\n  \"google.golang.org\u002Fgrpc\u002Fcredentials\u002Finsecure\"\n  \"google.golang.org\u002Fgrpc\u002Fgrpclog\"\n\n  gw \"github.com\u002Fyourorg\u002Fyourrepo\u002Fproto\u002Fgen\u002Fgo\u002Fyour\u002Fservice\u002Fv1\u002Fyour_service\"  \u002F\u002F Update\n)\n\nvar (\n  \u002F\u002F command-line options:\n  \u002F\u002F gRPC server endpoint\n  grpcServerEndpoint = flag.String(\"grpc-server-endpoint\",  \"localhost:9090\", \"gRPC server endpoint\")\n)\n\nfunc run() error {\n  ctx := context.Background()\n  ctx, cancel := context.WithCancel(ctx)\n  defer cancel()\n\n  \u002F\u002F Register gRPC server endpoint\n  \u002F\u002F Note: Make sure the gRPC server is running properly and accessible\n  mux := runtime.NewServeMux()\n  opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())}\n  err := gw.RegisterYourServiceHandlerFromEndpoint(ctx, mux,  *grpcServerEndpoint, opts)\n  if err != nil {\n    return err\n  }\n\n  \u002F\u002F Start HTTP server (and proxy calls to gRPC server endpoint)\n  return http.ListenAndServe(\":8081\", mux)\n}\n\nfunc main() {\n  flag.Parse()\n\n  if err := run(); err != nil {\n    grpclog.Fatal(err)\n  }\n}\n```\n\n### 6. (Optional) Generate OpenAPI definitions using `protoc-gen-openapiv2`\n\nHere's what a `buf.gen.yaml` file might look like:\n\n```yaml\nversion: v2\nplugins:\n  - local: protoc-gen-go\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - local: protoc-gen-go-grpc\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - local: protoc-gen-grpc-gateway\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n      - generate_unbound_methods=true\n  - local: protoc-gen-openapiv2\n    out: gen\u002Fgo\n```\n\nTo use the custom protobuf annotations supported by `protoc-gen-openapiv2`, we need\nanother dependency added to our protobuf generation step. If you are using\n`buf`, you can add the `buf.build\u002Fgrpc-ecosystem\u002Fgrpc-gateway` dependency\nto your `deps` array:\n\n```yaml\nversion: v2\nname: buf.build\u002Fyourorg\u002Fmyprotos\ndeps:\n  - buf.build\u002Fgoogleapis\u002Fgoogleapis\n  - buf.build\u002Fgrpc-ecosystem\u002Fgrpc-gateway\n```\n\nWith `protoc` (just the swagger file):\n\n```sh\nprotoc -I . --openapiv2_out .\u002Fgen\u002Fopenapiv2 \\\n    your\u002Fservice\u002Fv1\u002Fyour_service.proto\n```\n\nIf you are using `protoc` to generate stubs, you will need to copy the protobuf\nfiles from the `protoc-gen-openapiv2\u002Foptions` directory of this repository,\nand providing them to `protoc` when running.\n\nNote that this plugin also supports generating OpenAPI definitions for unannotated methods;\nuse the `generate_unbound_methods` option to enable this.\n\nIt is possible with the HTTP mapping for a gRPC service method to create duplicate mappings\nwith the only difference being constraints on the path parameter.\n\n`\u002Fv1\u002F{name=projects\u002F*}` and `\u002Fv1\u002F{name=organizations\u002F*}` both become `\u002Fv1\u002F{name}`. When\nthis occurs the plugin will rename the path parameter with a \"\\_1\" (or \"\\_2\" etc) suffix\nto differentiate the different operations. So in the above example, the 2nd path would become\n`\u002Fv1\u002F{name_1=organizations\u002F*}`. This can also cause OpenAPI clients to URL encode the \"\u002F\" that is\npart of the path parameter as that is what OpenAPI defines in the specification. To allow gRPC gateway to\naccept the URL encoded slash and still route the request, use the UnescapingModeAllCharacters or\nUnescapingModeLegacy (which is the default currently though may change in future versions). See\n[Customizing Your Gateway](https:\u002F\u002Fgrpc-ecosystem.github.io\u002Fgrpc-gateway\u002Fdocs\u002Fmapping\u002Fcustomizing_your_gateway\u002F)\nfor more information.\n\n#### Alternative: OpenAPI 3.1 with `protoc-gen-openapiv3`\n\n> ⚠️ **Alpha.** `protoc-gen-openapiv3` is new and its output is not yet\n> stable. Expect breaking changes to the emitted JSON shape (oneof\n> encodings, wrapper types, enum form, path-template expansion, etc.)\n> between minor releases while the mapping rules settle in response to\n> real-world feedback. Use it if you want to follow that evolution;\n> otherwise `protoc-gen-openapiv2` remains the stable choice.\n\n`protoc-gen-openapiv3` is a separate generator that emits OpenAPI\n**3.1.0** JSON directly from `google.api.http` annotations. It's a good\nchoice when your downstream tooling requires 3.1, when you want the richer\nJSON Schema 2020-12 constructs (proper `oneOf` encoding for proto oneofs,\nspec-accurate literal expansion of constrained path templates like\n`{name=shelves\u002F*\u002Fbooks\u002F*}`, etc.).\n\nAdd it to your `buf.gen.yaml` alongside (or instead of) `protoc-gen-openapiv2`:\n\n```yaml\nversion: v2\nplugins:\n  - local: protoc-gen-openapiv3\n    out: gen\u002Fopenapiv3\n```\n\nOr invoke it directly with `protoc`:\n\n```sh\nprotoc -I. --openapiv3_out=.\u002Fgen\u002Fopenapiv3 your\u002Fservice\u002Fv1\u002Fyour_service.proto\n```\n\nA `.openapi.json` file appears next to each proto file that declares HTTP\nbindings; files with no HTTP-bound services produce no output.\nSee [OpenAPI 3.1 Output](https:\u002F\u002Fgrpc-ecosystem.github.io\u002Fgrpc-gateway\u002Fdocs\u002Fmapping\u002Fopenapi_v3\u002F) for\nmore information about the capabilities of protoc-gen-openapiv3.\n\n## Usage with remote plugins\n\nAs an alternative to all of the above, you can use `buf` with\n[remote plugins](https:\u002F\u002Fbuf.build\u002Fdocs\u002Fbsr\u002Fremote-plugins\u002Fusage)\nto manage plugin versions and generation. An example `buf.gen.yaml` using remote\nplugin generation looks like this:\n\n```yaml\nversion: v2\nplugins:\n  - remote: buf.build\u002Fprotocolbuffers\u002Fgo:v1.31.0\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - remote: buf.build\u002Fgrpc\u002Fgo:v1.3.0\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - remote: buf.build\u002Fgrpc-ecosystem\u002Fgateway:v2.16.2\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n  - remote: buf.build\u002Fgrpc-ecosystem\u002Fopenapiv2:v2.16.2\n    out: gen\u002Fopenapiv2\n```\n\nThis requires no local installation of any plugins. Be careful to use the same\nversion of the generator as the runtime library, i.e. if using `v2.16.2`, run\n\n```shell\n$ go get github.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fv2@v2.16.2\n```\n\nTo get the same version of the runtime in your `go.mod`.\n\nNote that usage of remote plugins is incompatible with usage of external configuration files like [grpc_api_configuration](https:\u002F\u002Fgrpc-ecosystem.github.io\u002Fgrpc-gateway\u002Fdocs\u002Fmapping\u002Fgrpc_api_configuration\u002F#using-an-external-configuration-file).\n\n## Video intro\n\nThis GopherCon UK 2019 presentation from our maintainer [@JohanBrandhorst](https:\u002F\u002Fgithub.com\u002Fjohanbrandhorst) provides a good intro to using the gRPC-Gateway. It uses the following boilerplate repo as a base: https:\u002F\u002Fgithub.com\u002Fjohanbrandhorst\u002Fgrpc-gateway-boilerplate.\n\n\u003Cdiv align=\"center\">\n\u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=Pq1paKC-fXk\">\n\u003Cimg src=\"https:\u002F\u002Fimg.youtube.com\u002Fvi\u002FPq1paKC-fXk\u002F0.jpg\" \u002F>\n\u003C\u002Fa>\n\u003C\u002Fdiv>\n\n## Parameters and flags\n\nWhen using `buf` to generate stubs, flags and parameters are passed through\nthe `opt` field in your `buf.gen.yaml` file, for example:\n\n```yaml\nversion: v2\nplugins:\n  - local: protoc-gen-grpc-gateway\n    out: gen\u002Fgo\n    opt:\n      - paths=source_relative\n      - grpc_api_configuration=path\u002Fto\u002Fconfig.yaml\n      - standalone=true\n```\n\nDuring code generation with `protoc`, flags to gRPC-Gateway tools must be passed\nthrough `protoc` using one of 2 patterns:\n\n- as part of the `--\u003Ctool_suffix>_out` `protoc` parameter: `--\u003Ctool_suffix>_out=\u003Cflags>:\u003Cpath>`\n\n```sh\n--grpc-gateway_out=repeated_path_param_separator=ssv:.\n--openapiv2_out=repeated_path_param_separator=ssv:.\n```\n\n- using additional `--\u003Ctool_suffix>_opt` parameters: `--\u003Ctool_suffix>_opt=\u003Cflag>[,\u003Cflag>]*`\n\n```sh\n--grpc-gateway_opt repeated_path_param_separator=ssv\n--openapiv2_opt repeated_path_param_separator=ssv\n```\n\n## More examples\n\nMore examples are available under the `examples` directory.\n\n- `proto\u002Fexamplepb\u002Fecho_service.proto`, `proto\u002Fexamplepb\u002Fa_bit_of_everything.proto`, `proto\u002Fexamplepb\u002Funannotated_echo_service.proto`: service definition\n  - `proto\u002Fexamplepb\u002Fecho_service.pb.go`, `proto\u002Fexamplepb\u002Fa_bit_of_everything.pb.go`, `proto\u002Fexamplepb\u002Funannotated_echo_service.pb.go`: [generated] stub of the service\n  - `proto\u002Fexamplepb\u002Fecho_service.pb.gw.go`, `proto\u002Fexamplepb\u002Fa_bit_of_everything.pb.gw.go`, `proto\u002Fexamplepb\u002Fuannotated_echo_service.pb.gw.go`: [generated] reverse proxy for the service\n  - `proto\u002Fexamplepb\u002Funannotated_echo_service.yaml`: gRPC API Configuration for `unannotated_echo_service.proto`\n- `server\u002Fmain.go`: service implementation\n- `main.go`: entrypoint of the generated reverse proxy\n\nTo use the same port for custom HTTP handlers (e.g. serving `swagger.json`),\ngRPC-Gateway, and a gRPC server, see\n[this example by CoreOS](https:\u002F\u002Fgithub.com\u002Fphilips\u002Fgrpc-gateway-example\u002Fblob\u002Fmaster\u002Fcmd\u002Fserve.go)\n(and its accompanying [blog post](https:\u002F\u002Fweb.archive.org\u002Fweb\u002F20201112010739\u002Fhttps:\u002F\u002Fcoreos.com\u002Fblog\u002Fgrpc-protobufs-swagger.html)).\n\n[This example by neiro.ai](https:\u002F\u002Fgithub.com\u002Fmynalabsai\u002Fgrpc_gateway_media_example) (and its accompanying [blog post](https:\u002F\u002Fmedium.com\u002Fneiro-ai\u002Fgrpc-gateway-for-media-api-by-neiro-9033caab12c8)) shows how mediafiles using `multipart\u002Fform-data` can be integrated into rpc messages using a middleware.\n\n## Features\n\n### Supported\n\n- Generating JSON API handlers.\n- Method parameters in the request body.\n- Method parameters in the request path.\n- Method parameters in the query string.\n- Enum fields in the path parameter (including repeated enum fields).\n- Mapping streaming APIs to newline-delimited JSON streams.\n- Mapping HTTP headers with `Grpc-Metadata-` prefix to gRPC metadata (prefixed with `grpcgateway-`)\n- Optionally emitting API definitions for\n  [OpenAPI (Swagger) v2](https:\u002F\u002Fswagger.io\u002Fdocs\u002Fspecification\u002F2-0\u002Fbasic-structure\u002F).\n- Setting [gRPC timeouts](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc\u002Fblob\u002Fmaster\u002Fdoc\u002FPROTOCOL-HTTP2.md#requests)\n  through inbound HTTP `Grpc-Timeout` header.\n- Partial support for [gRPC API Configuration](https:\u002F\u002Fcloud.google.com\u002Fendpoints\u002Fdocs\u002Fgrpc\u002Fgrpc-service-config)\n  files as an alternative to annotation.\n- Automatically translating PATCH requests into Field Mask gRPC requests. See\n  [the docs](https:\u002F\u002Fgrpc-ecosystem.github.io\u002Fgrpc-gateway\u002Fdocs\u002Fmapping\u002Fpatch_feature\u002F)\n  for more information.\n- [Protobuf Editions](https:\u002F\u002Fprotobuf.dev\u002Feditions\u002Foverview\u002F) support (edition 2023).\n- Go [Opaque API](https:\u002F\u002Fgo.dev\u002Fblog\u002Fprotobuf-opaque) support.\n\n### No plan to support\n\nBut patches are welcome.\n\n- Method parameters in HTTP headers.\n- Handling trailer metadata.\n- Encoding request\u002Fresponse body in XML.\n- True bi-directional streaming.\n\n## Mapping gRPC to HTTP\n\n- [How gRPC error codes map to HTTP status codes in the response](https:\u002F\u002Fgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fblob\u002Fmain\u002Fruntime\u002Ferrors.go#L15).\n- HTTP request source IP is added as `X-Forwarded-For` gRPC request header.\n- HTTP request host is added as `X-Forwarded-Host` gRPC request header.\n- HTTP `Authorization` header is added as `authorization` gRPC request header.\n- Remaining Permanent HTTP header keys (as specified by the IANA\n  [here](http:\u002F\u002Fwww.iana.org\u002Fassignments\u002Fmessage-headers\u002Fmessage-headers.xhtml))\n  are prefixed with `grpcgateway-` and added with their values to gRPC request\n  header.\n- HTTP headers that start with 'Grpc-Metadata-' are mapped to gRPC metadata\n  (prefixed with `grpcgateway-`).\n- While configurable, the default {un,}marshaling uses\n  [protojson](https:\u002F\u002Fpkg.go.dev\u002Fgoogle.golang.org\u002Fprotobuf\u002Fencoding\u002Fprotojson).\n- The path template used to map gRPC service methods to HTTP endpoints supports the [google.api.http](https:\u002F\u002Fgithub.com\u002Fgoogleapis\u002Fgoogleapis\u002Fblob\u002Fmaster\u002Fgoogle\u002Fapi\u002Fhttp.proto)\n  path template syntax. For example, `\u002Fapi\u002Fv1\u002F{name=projects\u002F*\u002Ftopics\u002F*}` or `\u002Fprefix\u002F{path=organizations\u002F**}`.\n\n## Contribution\n\nSee [CONTRIBUTING.md](http:\u002F\u002Fgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fblob\u002Fmain\u002FCONTRIBUTING.md).\n\n## License\n\ngRPC-Gateway is licensed under the BSD 3-Clause License.\nSee [LICENSE](https:\u002F\u002Fgithub.com\u002Fgrpc-ecosystem\u002Fgrpc-gateway\u002Fblob\u002Fmain\u002FLICENSE) for more details.\n","gRPC-Gateway 是一个将 gRPC 服务转换为 RESTful HTTP API 的代理生成器。它通过解析带有 `google.api.http` 注解的 Protocol Buffers 服务定义，自动生成一个反向代理服务器，该服务器能够将 RESTful 风格的 HTTP 请求转换成 gRPC 调用，使得开发者可以同时以 gRPC 和 RESTful 格式提供相同的服务。项目采用 Go 语言编写，支持 OpenAPI 规范与 Swagger 文档生成，适用于需要同时维护 gRPC 和 RESTful API 的场景，如保持向后兼容性、支持不完全兼容 gRPC 的客户端或编程语言等。",2,"2026-06-11 03:00:39","top_language"]