{"id":13832021,"url":"https://github.com/googleapis/gapic-generator-go","last_synced_at":"2026-02-06T21:07:17.245Z","repository":{"id":33691731,"uuid":"149170309","full_name":"googleapis/gapic-generator-go","owner":"googleapis","description":"Generate Go API client libraries from Protocol Buffers.","archived":false,"fork":false,"pushed_at":"2025-03-13T19:42:38.000Z","size":3466,"stargazers_count":267,"open_issues_count":32,"forks_count":51,"subscribers_count":49,"default_branch":"main","last_synced_at":"2025-04-01T09:33:54.549Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/googleapis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-17T18:31:01.000Z","updated_at":"2025-03-28T10:41:54.000Z","dependencies_parsed_at":"2023-10-13T09:14:31.098Z","dependency_job_id":"a0cc5a34-e3f5-4490-a87d-cc7c065393c1","html_url":"https://github.com/googleapis/gapic-generator-go","commit_stats":{"total_commits":1349,"total_committers":35,"mean_commits":"38.542857142857144","dds":0.6093402520385471,"last_synced_commit":"4baec556a6836e153ed75f253f7b2778f9ca4a99"},"previous_names":[],"tags_count":158,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleapis%2Fgapic-generator-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleapis%2Fgapic-generator-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleapis%2Fgapic-generator-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleapis%2Fgapic-generator-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/googleapis","download_url":"https://codeload.github.com/googleapis/gapic-generator-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247829511,"owners_count":21002997,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T10:01:48.064Z","updated_at":"2026-02-06T21:07:17.205Z","avatar_url":"https://github.com/googleapis.png","language":"Go","readme":"# API Client Generator for Go\n\n![latest release](https://img.shields.io/github/v/release/googleapis/gapic-generator-go)\n![Go version](https://img.shields.io/github/go-mod/go-version/googleapis/gapic-generator-go)\n\nA generator for protocol buffer described APIs for and in Go.\n\nThis is a generator for API client libraries for APIs specified by protocol buffers, such as those inside Google.\nIt takes a protocol buffer (with particular annotations) and uses it to generate a client library.\n\n## Purpose\n\nWe aim for this generator to replace the [older monolithic generator](https://github.com/googleapis/gapic-generator).\nSome areas we hope to improve over the old generator are:\n\n- using explicit normalized format for specifying APIs,\n- simpler, faster implementation, and\n- better error reporting.\n\n## Installation\n\n`go install github.com/googleapis/gapic-generator-go/cmd/protoc-gen-go_gapic@latest`.\nIf you are using Go 1.11 and see error `cannot find main module`, see this [FAQ page](https://github.com/golang/go/wiki/Modules#why-does-installing-a-tool-via-go-get-fail-with-error-cannot-find-main-module).\n\nOr to install from source:\n\n```bash\ngit pull https://github.com/googleapis/gapic-generator-go.git\ncd gapic-generator-go\ngo install ./cmd/protoc-gen-go_gapic\n```\n\nThe generator works as a `protoc` plugin, get `protoc` from [google/protobuf](https://github.com/protocolbuffers/protobuf).\n\n## Configuration\n\nThe generator is configured via protobuf annotations found at [googleapis/api-common-protos](https://github.com/googleapis/api-common-protos).\nThe generator follows the guidance defined in [AIP-4210](https://aip.dev/4210).\n\nThe only *required* annotation to generate a client is the service annotation `google.api.default_host` ([here](https://github.com/googleapis/googleapis/blob/82528cf321ed0d09b7d93b7cee9122ccea422ad2/google/api/client.proto#L67-L76)).\n\nThe value of `google.api.default_host` must be just a host name, excluding a scheme. For example,\n\n```go\nimport \"google/api/client.proto\";\n...\n\nservice Foo {\n    option (google.api.default_host) = \"api.foo.com\";\n    ...\n}  \n```\n\nIf a RPC returns a `google.longrunning.Operation`, the RPC must be annotated with `google.longrunning.operation_info` in accordance with [AIP-151](https://aip.dev/151).\n\nThe [Cloud Natural Language API](https://github.com/googleapis/googleapis/blob/master/google/cloud/language/v1/language_service.proto) is an example of a fully configured API that has a [Go client](https://github.com/googleapis/google-cloud-go/tree/main/language/apiv1) generated by gapic-generator-go.\n\nThe supported configuration annotations include:\n\n- Service Options\n  - `google.api.default_host`: host name used in the default service client initialization\n  - `google.api.oauth_scopes`: OAuth scopes needed by the client to auth'n/z\n- Method Options\n  - `google.longrunning.operation_info`: used to determine response \u0026 metadata types of LRO methods\n\n## Invocation\n\n`protoc -I $GOOGLEAPIS --go_gapic_out [OUTPUT_DIR] --go_gapic_opt 'go-gapic-package=package/path/url;name' a.proto b.proto`\n\n**Note:** The `$GOOGLEAPIS` variable represents a path to the [googleapis/googleapis](https://github.com/googleapis/googleapis) directory to import the configuration annotations.\n\nThe `go_gapic_opt` protoc plugin option flag is necessary to convey configuration information not present in the protos.\nThe plugin option's value is a key-value pair delimited by an equal sign `=`.\nThe configuration supported by the plugin option includes:\n  \n- `go-gapic-package`: the Go package of the generated client library.\n  - The substring preceding the semicolon is the import path of the package, e.g. `github.com/username/awesomeness`.\n  - The substring after the semicolon is the name of the package used in the `package` statement.\n  - **Note:** Idiomatically the name is last element of the path but it need not be.\n  For instance, the last element of the path might be the package's version, and the package would benefit\n  from a more descriptive name.\n\n- `module`: prefix to be stripped from the `go-gapic-package` used in the generated filenames.\n  - **Note:** This option is not supported from the Bazel interface.\n\n- `metadata`: enable generation of [GapicMetadata](https://github.com/googleapis/googleapis/blob/master/gapic/metadata/gapic_metadata.proto) in JSON form. The default is `false`.\n\n- `grpc-service-config`: the path to a gRPC ServiceConfig JSON file.\n  - This is used for client-side retry configuration in accordance with [AIP-4221](http://aip.dev/4221)\n\n- `release-level`: the client library release level.\n  - Defaults to empty, which is essentially the GA release level.\n  - Acceptable values are `alpha` and `beta`.\n\n- `api-service-config`: the path the service YAML file.\n  - This is used for service-level client documentation.\n\n- `transport`: the desired transport(s) to generate, delimited by `+` e.g. `grpc+rest`.\n  - Acceptable values are `grpc` and `rest`.\n  - Defaults to `grpc`.\n\n- `rest-numeric-enums`: enables requesting response enums be encoded as numbers.\n  - Not enabled by default.\n  - Only effective when `rest` is included as a `transport` to be generated.\n\n- `omit-snippets`: disable generation of code snippets to the `internal/generated/snippets` path. The default is `false`.\n\n## Bazel\n\nThe generator can be executed via a Bazel BUILD file using the macro in this repo.\n\nAdd the following to your WORKSPACE to import this project.\n\n```bazel\nload(\"@bazel_tools//tools/build_defs/repo:http.bzl\", \"http_archive\")\n\nhttp_archive(\n    name = \"com_googleapis_gapic_generator_go\",\n    strip_prefix = \"gapic-generator-go-main\",\n    urls = [\"https://github.com/googleapis/gapic-generator-go/archive/main.zip\"],\n)\n\nload(\"@com_googleapis_gapic_generator_go//:repositories.bzl\", \"com_googleapis_gapic_generator_go_repositories\")\n\ncom_googleapis_gapic_generator_go_repositories()\n```\n\n**Note:** do not use `main`, use a commit hash or a release tag.\n\nAnd invoke it in a BUILD file like so, using an example based on the [googleapis repo](https://github.com/googleapis/googleapis/tree/92bebf78345af8b2d3585220527115bda8bdedf8/google/cloud/language/v1).\n\n```bazel\nload(\"@com_googleapis_gapic_generator_go//rules_go_gapic:go_gapic.bzl\", \"go_gapic_library\")\n\ngo_gapic_library(\n  name = \"language_go_gapic\",\n  srcs = [\n    # BUILD target for proto_library\n    \"//google/cloud/language/v1:language_proto\",\n  ],\n  deps = [\n    # BUILD target for go_library_proto\n    \"//google/cloud/language/v1:language_go_proto\",\n  ],\n  # go-gapic-package parameter value\n  importpath = \"cloud.google.com/go/language/apiv1;language\",\n)\n```\n\nThe generator options defined in [Invocation](#invocation) are supported as the\nfollowing attributes:\n\n- `grpc_service_config`: a label for a gRPC ServiceConfig JSON file.\n\n- `release_level`: the client library release level.\n\n- `service_yaml`: a label for a service YAML file.\n  - **Note:** This option will eventually be deprecated.\n\n- `metadata`: if `True`, [GapicMetadata](https://github.com/googleapis/googleapis/blob/master/gapic/metadata/gapic_metadata.proto) will be generated in JSON form. The default is `False`.\n\n- `transport`: the desired transport(s) to generate, delimited by `+` e.g. `grpc+rest`.\n  - Acceptable values are `grpc` and `rest`.\n  - Defaults to `grpc`.\n\n- `rest_numeric_enums`: if `True`, enables generation of system parameter requesting\nresponse enums be encoded as numbers.\n  - Default is `False`.\n  - Only effective when `rest` is included as a `transport` to be generated.\n\n- `omit_snippets`: if `True`, code snippets will be generated to the `internal/generated/snippets` path. The default is `True`.\n\n## Docker Wrapper\n\nThe generator can also be executed via a Docker container. The image containes `protoc`, the microgenerator\nbinary, and the standard API protos.\n\n```bash\n$ docker run \\\n  --rm \\\n  --user $UID \\\n  --mount type=bind,source=\u003c/abs/path/to/protos\u003e,destination=/in,readonly \\\n  --mount type=bind,source=\u003c/abs/path/to/configs\u003e,destination=/conf,readonly \\\n  --mount type=bind,source=$GOPATH/src,destination=/out/ \\\n  gcr.io/gapic-images/gapic-generator-go \\\n  --go-gapic-package \"github.com/package/import/path;name\"\n```\n\nReplace `/abs/path/to/protos` with the absolute path to the input protos and `github.com/package/import/path;name`\nwith the desired import path \u0026 name for the `gapic`, as described in [Invocation](#invocation).\n\nFor convenience, the [gapic.sh](./gapic.sh) script wraps the above `docker` invocation.\nAn equivalent invocation using `gapic.sh` is:\n\n```bash\n$ gapic.sh \\\n  --image gcr.io/gapic-images/gapic-generator-go \\\n  --in /abs/path/to/protos \\\n  --out $GOPATH/src \\\n  --go-gapic-package \"\u003cgithub.com/package/import/path;name\u003e\"\n```\n\nUse `gapic.sh --help` to print the usage documentation.\n\n## Code Generation\n\nThis is an explanation of the Go GAPIC generator for those interested in how it works and possibly those using it as a reference.\n\n### Plugin interface\n\n`gapic-generator-go` is a `protoc` [plugin](https://developers.google.com/protocol-buffers/docs/reference/other). It consumes a serialzed `CodeGeneratorRequest` on `stdin` and produces a serialized `CodeGeneratorResponse` on `stdout`. The `CodeGeneratorResponse` contains all of the generated Go code and/or any error(s) that might of occured during generation. All logs are emitted on `stderr`.\n\nThe plugin implementation can be found in [cmd/protoc-gen-go_gapic](/cmd/protoc-gen-go_gapic).\n\n### Generated Artifacts\n\nA single invocation of the code generator creates a `doc.go` file package level documentation according to [godoc](https://blog.golang.org/godoc-documenting-go-code).  This documentation is (currently) pulled from a given service config.\n\nEach service found in the input protos gets two generated artifacts:\n\n- `{service}_client.go`: contains the GAPIC implementation\n- `{service}_client_example_test.go`: contains example code for each service method, consumed by [godoc](https://blog.golang.org/examples)\n\nThere is no directory structure in the generated output. All files are placed directly in the designated output directory by `protoc`.\n\n### Generation Process\n\nThe generator implementation can be found in [internal/gengapic](/internal/gengapic).\n\nThe service client type, initialization code and any standard helpers are generated first. Then each method is generated. Any relevant helper types (i.e. pagination [Iterator](https://github.com/googleapis/google-cloud-go/wiki/Iterator-Guidelines) types, LRO helpers, etc.) for the service methods are generated following the methods.\n\nFollowing the client implementation, the client example file is generated, and after all services have been generated the single `doc.go` file is created.\n\n## Go Version Supported\n\nThe generator itself supports the latest version.\n\nThe generated code is compatible with Go 1.6.\n\n## Contributing\n\nIf you are looking to contribute to the project, please see CONTRIBUTING.md for guidelines.\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleapis%2Fgapic-generator-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogleapis%2Fgapic-generator-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleapis%2Fgapic-generator-go/lists"}