Skip to content

Commit

Permalink
Merge branch 'main' into insecure
Browse files Browse the repository at this point in the history
  • Loading branch information
@quartzmo
quartzmo committed May 6, 2024
2 parents 75a5416 + 0452588 commit 3006333
Show file tree
Hide file tree
Showing 5 changed files with 129 additions and 140 deletions.
153 changes: 76 additions & 77 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
API Client Generator for Go
===========================
# API Client Generator for Go

![latest release](https://img.shields.io/github/v/release/googleapis/gapic-generator-go)
![Go version](https://img.shields.io/github/go-mod/go-version/googleapis/gapic-generator-go)
Expand All @@ -9,37 +8,40 @@ A generator for protocol buffer described APIs for and in Go.
This is a generator for API client libraries for APIs specified by protocol buffers, such as those inside Google.
It takes a protocol buffer (with particular annotations) and uses it to generate a client library.

Purpose
-------
## Purpose

We aim for this generator to replace the [older monolithic generator](https://github.com/googleapis/gapic-generator).
Some areas we hope to improve over the old generator are:

- using explicit normalized format for specifying APIs,
- simpler, faster implementation, and
- better error reporting.

Installation
------------
## Installation

`go install github.com/googleapis/gapic-generator-go/cmd/protoc-gen-go_gapic@latest`.
If 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).

Or to install from source:
```

```bash
git pull https://github.com/googleapis/gapic-generator-go.git
cd gapic-generator-go
go install ./cmd/protoc-gen-go_gapic
```

The generator works as a `protoc` plugin, get `protoc` from [google/protobuf](https://github.com/protocolbuffers/protobuf).

Configuration
-------------
## Configuration

The generator is configured via protobuf annotations found at [googleapis/api-common-protos](https://github.com/googleapis/api-common-protos).
The generator follows the guidance defined in [AIP-4210](https://aip.dev/4210).

The 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)).

The value of `google.api.default_host` must be just a host name, excluding a scheme. For example,
```

```go
import "google/api/client.proto";
...

Expand All @@ -54,63 +56,62 @@ If a RPC returns a `google.longrunning.Operation`, the RPC must be annotated wit
The [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.

The supported configuration annotations include:
* Service Options
* `google.api.default_host`: host name used in the default service client initialization
* `google.api.oauth_scopes`: OAuth scopes needed by the client to auth'n/z
* Method Options
* `google.longrunning.operation_info`: used to determine response & metadata types of LRO methods

Invocation
----------

- Service Options
- `google.api.default_host`: host name used in the default service client initialization
- `google.api.oauth_scopes`: OAuth scopes needed by the client to auth'n/z
- Method Options
- `google.longrunning.operation_info`: used to determine response & metadata types of LRO methods

## Invocation

`protoc -I $GOOGLEAPIS --go_gapic_out [OUTPUT_DIR] --go_gapic_opt 'go-gapic-package=package/path/url;name' a.proto b.proto`

**Note:** The `$GOOGLEAPIS` variable represents a path to the [googleapis/googleapis](https://github.com/googleapis/googleapis) directory to import the configuration annotations.

The `go_gapic_opt` protoc plugin option flag is necessary to convey configuration information not present in the protos.
The `go_gapic_opt` protoc plugin option flag is necessary to convey configuration information not present in the protos.
The plugin option's value is a key-value pair delimited by an equal sign `=`.
The configuration supported by the plugin option includes:

* `go-gapic-package`: the Go package of the generated client library.
* The substring preceding the semicolon is the import path of the package, e.g. `github.com/username/awesomeness`.
* The substring after the semicolon is the name of the package used in the `package` statement.

**Note:** Idiomatically the name is last element of the path but it need not be.
For instance, the last element of the path might be the package's version, and the package would benefit
from a more descriptive name.

* `module`: prefix to be stripped from the `go-gapic-package` used in the generated filenames.
* _Note: This option is not supported from the Bazel interface._

* `metadata`: enable generation of [GapicMetadata](https://github.com/googleapis/googleapis/blob/master/gapic/metadata/gapic_metadata.proto) in JSON form. The default is `false`.

* `grpc-service-config`: the path to a gRPC ServiceConfig JSON file.
* This is used for client-side retry configuration in accordance with [AIP-4221](http://aip.dev/4221)
- `go-gapic-package`: the Go package of the generated client library.
- The substring preceding the semicolon is the import path of the package, e.g. `github.com/username/awesomeness`.
- The substring after the semicolon is the name of the package used in the `package` statement.
- **Note:** Idiomatically the name is last element of the path but it need not be.
For instance, the last element of the path might be the package's version, and the package would benefit
from a more descriptive name.

- `module`: prefix to be stripped from the `go-gapic-package` used in the generated filenames.
- **Note:** This option is not supported from the Bazel interface.

- `metadata`: enable generation of [GapicMetadata](https://github.com/googleapis/googleapis/blob/master/gapic/metadata/gapic_metadata.proto) in JSON form. The default is `false`.

* `release-level`: the client library release level.
* Defaults to empty, which is essentially the GA release level.
* Acceptable values are `alpha` and `beta`.
- `grpc-service-config`: the path to a gRPC ServiceConfig JSON file.
- This is used for client-side retry configuration in accordance with [AIP-4221](http://aip.dev/4221)

* `api-service-config`: the path the service YAML file.
* This is used for service-level client documentation.
- `release-level`: the client library release level.
- Defaults to empty, which is essentially the GA release level.
- Acceptable values are `alpha` and `beta`.

* `transport`: the desired transport(s) to generate, delimited by `+` e.g. `grpc+rest`.
* Acceptable values are `grpc` and `rest`.
* Defaults to `grpc`.
- `api-service-config`: the path the service YAML file.
- This is used for service-level client documentation.

* `rest-numeric-enums`: enables requesting response enums be encoded as numbers.
* Not enabled by default.
* Only effective when `rest` is included as a `transport` to be generated.
- `transport`: the desired transport(s) to generate, delimited by `+` e.g. `grpc+rest`.
- Acceptable values are `grpc` and `rest`.
- Defaults to `grpc`.

* `omit-snippets`: disable generation of code snippets to the `internal/generated/snippets` path. The default is `false`.
- `rest-numeric-enums`: enables requesting response enums be encoded as numbers.
- Not enabled by default.
- Only effective when `rest` is included as a `transport` to be generated.

Bazel
-----
- `omit-snippets`: disable generation of code snippets to the `internal/generated/snippets` path. The default is `false`.

## Bazel

The generator can be executed via a Bazel BUILD file using the macro in this repo.

Add the following to your WORKSPACE to import this project.

```
```bazel
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
Expand All @@ -124,11 +125,11 @@ load("@com_googleapis_gapic_generator_go//:repositories.bzl", "com_googleapis_ga
com_googleapis_gapic_generator_go_repositories()
```

_Note: do not use `main`, use a commit hash or a release tag._
**Note:** do not use `main`, use a commit hash or a release tag.

And 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).

```
```bazel
load("@com_googleapis_gapic_generator_go//rules_go_gapic:go_gapic.bzl", "go_gapic_library")

go_gapic_library(
Expand All @@ -146,31 +147,31 @@ go_gapic_library(
)
```

The generator options defined in [Invocation](#Invocation) are supported as the
The generator options defined in [Invocation](#invocation) are supported as the
following attributes:

* `grpc_service_config`: a label for a gRPC ServiceConfig JSON file.
- `grpc_service_config`: a label for a gRPC ServiceConfig JSON file.

* `release_level`: the client library release level.
- `release_level`: the client library release level.

* `service_yaml`: a label for a service YAML file.
* _Note: This option will eventually be deprecated._
- `service_yaml`: a label for a service YAML file.
- **Note:** This option will eventually be deprecated.

* `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`.
- `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`.

* `transport`: the desired transport(s) to generate, delimited by `+` e.g. `grpc+rest`.
* Acceptable values are `grpc` and `rest`.
* Defaults to `grpc`.
- `transport`: the desired transport(s) to generate, delimited by `+` e.g. `grpc+rest`.
- Acceptable values are `grpc` and `rest`.
- Defaults to `grpc`.

* `rest_numeric_enums`: if `True`, enables generation of system parameter requesting
response enums be encoded as numbers.
* Default is `False`.
* Only effective when `rest` is included as a `transport` to be generated.
- `rest_numeric_enums`: if `True`, enables generation of system parameter requesting
response enums be encoded as numbers.
- Default is `False`.
- Only effective when `rest` is included as a `transport` to be generated.

* `omit_snippets`: if `True`, code snippets will be generated to the `internal/generated/snippets` path. The default is `True`.
- `omit_snippets`: if `True`, code snippets will be generated to the `internal/generated/snippets` path. The default is `True`.

## Docker Wrapper

Docker Wrapper
--------------
The generator can also be executed via a Docker container. The image containes `protoc`, the microgenerator
binary, and the standard API protos.

Expand All @@ -186,7 +187,7 @@ $ docker run \
```

Replace `/abs/path/to/protos` with the absolute path to the input protos and `github.com/package/import/path;name`
with the desired import path & name for the `gapic`, as described in [Invocation](#Invocation).
with the desired import path & name for the `gapic`, as described in [Invocation](#invocation).

For convenience, the [gapic.sh](./gapic.sh) script wraps the above `docker` invocation.
An equivalent invocation using `gapic.sh` is:
Expand All @@ -201,8 +202,7 @@ $ gapic.sh \

Use `gapic.sh --help` to print the usage documentation.

Code Generation
---------------
## Code Generation

This is an explanation of the Go GAPIC generator for those interested in how it works and possibly those using it as a reference.

Expand All @@ -218,8 +218,8 @@ A single invocation of the code generator creates a `doc.go` file package level

Each service found in the input protos gets two generated artifacts:

* `{service}_client.go`: contains the GAPIC implementation
* `{service}_client_example_test.go`: contains example code for each service method, consumed by [godoc](https://blog.golang.org/examples)
- `{service}_client.go`: contains the GAPIC implementation
- `{service}_client_example_test.go`: contains example code for each service method, consumed by [godoc](https://blog.golang.org/examples)

There is no directory structure in the generated output. All files are placed directly in the designated output directory by `protoc`.

Expand All @@ -231,13 +231,12 @@ The service client type, initialization code and any standard helpers are genera

Following the client implementation, the client example file is generated, and after all services have been generated the single `doc.go` file is created.

Go Version Supported
--------------------
## Go Version Supported

The generator itself supports the latest version.

The generated code is compatible with Go 1.6.

Contributing
------------
## Contributing

If you are looking to contribute to the project, please see CONTRIBUTING.md for guidelines.
If you are looking to contribute to the project, please see CONTRIBUTING.md for guidelines.
18 changes: 9 additions & 9 deletions go.mod
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
module github.com/googleapis/gapic-generator-go

require (
cloud.google.com/go/iam v1.1.7
cloud.google.com/go/longrunning v0.5.6
cloud.google.com/go/iam v1.1.8
cloud.google.com/go/longrunning v0.5.7
github.com/ghodss/yaml v1.0.0
github.com/google/go-cmp v0.6.0
github.com/jhump/protoreflect v1.16.0
gitlab.com/golang-commonmark/markdown v0.0.0-20211110145824-bf3e522c626a
golang.org/x/text v0.14.0
google.golang.org/genproto v0.0.0-20240415180920-8c6c420018be
google.golang.org/genproto/googleapis/api v0.0.0-20240415180920-8c6c420018be
google.golang.org/genproto/googleapis/rpc v0.0.0-20240415180920-8c6c420018be
google.golang.org/protobuf v1.33.1-0.20240423095020-c2b76eee36e7
golang.org/x/text v0.15.0
google.golang.org/genproto v0.0.0-20240429193739-8cf5692501f6
google.golang.org/genproto/googleapis/api v0.0.0-20240429193739-8cf5692501f6
google.golang.org/genproto/googleapis/rpc v0.0.0-20240429193739-8cf5692501f6
google.golang.org/protobuf v1.34.1
)

require (
Expand All @@ -21,8 +21,8 @@ require (
gitlab.com/golang-commonmark/linkify v0.0.0-20191026162114-a0c2df6c8f82 // indirect
gitlab.com/golang-commonmark/mdurl v0.0.0-20191124015652-932350d1cb84 // indirect
gitlab.com/golang-commonmark/puny v0.0.0-20191124015043-9f83538fa04f // indirect
golang.org/x/net v0.23.0 // indirect
golang.org/x/sys v0.18.0 // indirect
golang.org/x/net v0.24.0 // indirect
golang.org/x/sys v0.19.0 // indirect
google.golang.org/grpc v1.63.2 // indirect
gopkg.in/yaml.v2 v2.2.8 // indirect
)
Expand Down
40 changes: 19 additions & 21 deletions go.sum
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
cloud.google.com/go/iam v1.1.7 h1:z4VHOhwKLF/+UYXAJDFwGtNF0b6gjsW1Pk9Ml0U/IoM=
cloud.google.com/go/iam v1.1.7/go.mod h1:J4PMPg8TtyurAUvSmPj8FF3EDgY1SPRZxcUGrn7WXGA=
cloud.google.com/go/longrunning v0.5.6 h1:xAe8+0YaWoCKr9t1+aWe+OeQgN/iJK1fEgZSXmjuEaE=
cloud.google.com/go/longrunning v0.5.6/go.mod h1:vUaDrWYOMKRuhiv6JBnn49YxCPz2Ayn9GqyjaBT8/mA=
cloud.google.com/go/iam v1.1.8 h1:r7umDwhj+BQyz0ScZMp4QrGXjSTI3ZINnpgU2nlB/K0=
cloud.google.com/go/iam v1.1.8/go.mod h1:GvE6lyMmfxXauzNq8NbgJbeVQNspG+tcdL/W8QO1+zE=
cloud.google.com/go/longrunning v0.5.7 h1:WLbHekDbjK1fVFD3ibpFFVoyizlLRl73I7YKuAKilhU=
cloud.google.com/go/longrunning v0.5.7/go.mod h1:8GClkudohy1Fxm3owmBGid8W0pSgodEMwEAztp38Xng=
github.com/bufbuild/protocompile v0.10.0 h1:+jW/wnLMLxaCEG8AX9lD0bQ5v9h1RUiMKOBOT5ll9dM=
github.com/bufbuild/protocompile v0.10.0/go.mod h1:G9qQIQo0xZ6Uyj6CMNz0saGmx2so+KONo8/KrELABiY=
github.com/ghodss/yaml v1.0.0 h1:wQHKEahhL6wmXdzwWG11gIVCkOv05bNOh+Rxn0yngAk=
Expand All @@ -26,27 +26,25 @@ gitlab.com/golang-commonmark/puny v0.0.0-20191124015043-9f83538fa04f h1:Wku8eEde
gitlab.com/golang-commonmark/puny v0.0.0-20191124015043-9f83538fa04f/go.mod h1:Tiuhl+njh/JIg0uS/sOJVYi0x2HEa5rc1OAaVsb5tAs=
gitlab.com/opennota/wd v0.0.0-20180912061657-c5d65f63c638 h1:uPZaMiz6Sz0PZs3IZJWpU5qHKGNy///1pacZC9txiUI=
gitlab.com/opennota/wd v0.0.0-20180912061657-c5d65f63c638/go.mod h1:EGRJaqe2eO9XGmFtQCvV3Lm9NLico3UhFwUpCG/+mVU=
golang.org/x/net v0.23.0 h1:7EYJ93RZ9vYSZAIb2x3lnuvqO5zneoD6IvWjuhfxjTs=
golang.org/x/net v0.23.0/go.mod h1:JKghWKKOSdJwpW2GEx0Ja7fmaKnMsbu+MWVZTokSYmg=
golang.org/x/sync v0.6.0 h1:5BMeUDZ7vkXGfEr1x9B4bRcTH4lpkTkpdh0T/J+qjbQ=
golang.org/x/sys v0.18.0 h1:DBdB3niSjOA/O0blCZBqDefyWNYveAYMNF1Wum0DYQ4=
golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/net v0.24.0 h1:1PcaxkF854Fu3+lvBIx5SYn9wRlBzzcnHZSiaFFAb0w=
golang.org/x/net v0.24.0/go.mod h1:2Q7sJY5mzlzWjKtYUEXSlBWCdyaioyXzRB2RtU8KVE8=
golang.org/x/sync v0.7.0 h1:YsImfSBoP9QPYL0xyKJPq0gcaJdG3rInoqxTWbfQu9M=
golang.org/x/sys v0.19.0 h1:q5f1RH2jigJ1MoAWp2KTp3gm5zAGFUTarQZ5U386+4o=
golang.org/x/sys v0.19.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
golang.org/x/text v0.15.0 h1:h1V/4gjBv8v9cjcR6+AR5+/cIYK5N/WAgiv4xlsEtAk=
golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
google.golang.org/genproto v0.0.0-20240415180920-8c6c420018be h1:g4aX8SUFA8V5F4LrSY5EclyGYw1OZN4HS1jTyjB9ZDc=
google.golang.org/genproto v0.0.0-20240415180920-8c6c420018be/go.mod h1:FeSdT5fk+lkxatqJP38MsUicGqHax5cLtmy/6TAuxO4=
google.golang.org/genproto/googleapis/api v0.0.0-20240415180920-8c6c420018be h1:Zz7rLWqp0ApfsR/l7+zSHhY3PMiH2xqgxlfYfAfNpoU=
google.golang.org/genproto/googleapis/api v0.0.0-20240415180920-8c6c420018be/go.mod h1:dvdCTIoAGbkWbcIKBniID56/7XHTt6WfxXNMxuziJ+w=
google.golang.org/genproto/googleapis/rpc v0.0.0-20240415180920-8c6c420018be h1:LG9vZxsWGOmUKieR8wPAUR3u3MpnYFQZROPIMaXh7/A=
google.golang.org/genproto/googleapis/rpc v0.0.0-20240415180920-8c6c420018be/go.mod h1:WtryC6hu0hhx87FDGxWCDptyssuo68sk10vYjF+T9fY=
google.golang.org/genproto v0.0.0-20240429193739-8cf5692501f6 h1:MTmrc2F5TZKDKXigcZetYkH04YwqtOPEQJwh4PPOgfk=
google.golang.org/genproto v0.0.0-20240429193739-8cf5692501f6/go.mod h1:2ROWwqCIx97Y7CSyp11xB8fori0wzvD6+gbacaf5c8I=
google.golang.org/genproto/googleapis/api v0.0.0-20240429193739-8cf5692501f6 h1:DTJM0R8LECCgFeUwApvcEJHz85HLagW8uRENYxHh1ww=
google.golang.org/genproto/googleapis/api v0.0.0-20240429193739-8cf5692501f6/go.mod h1:10yRODfgim2/T8csjQsMPgZOMvtytXKTDRzH6HRGzRw=
google.golang.org/genproto/googleapis/rpc v0.0.0-20240429193739-8cf5692501f6 h1:DujSIu+2tC9Ht0aPNA7jgj23Iq8Ewi5sgkQ++wdvonE=
google.golang.org/genproto/googleapis/rpc v0.0.0-20240429193739-8cf5692501f6/go.mod h1:WtryC6hu0hhx87FDGxWCDptyssuo68sk10vYjF+T9fY=
google.golang.org/grpc v1.63.2 h1:MUeiw1B2maTVZthpU5xvASfTh3LDbxHd6IJ6QQVU+xM=
google.golang.org/grpc v1.63.2/go.mod h1:WAX/8DgncnokcFUldAxq7GeB5DXHDbMF+lLvDomNkRA=
google.golang.org/protobuf v1.33.1-0.20240408130810-98873a205002 h1:V7Da7qt0MkY3noVANIMVBk28nOnijADeOR3i5Hcvpj4=
google.golang.org/protobuf v1.33.1-0.20240408130810-98873a205002/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
google.golang.org/protobuf v1.33.1-0.20240423095020-c2b76eee36e7 h1:MMFfUWiqP3Byz55gWyVqia+CqXu504XM7v0ya1Gdu4c=
google.golang.org/protobuf v1.33.1-0.20240423095020-c2b76eee36e7/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
google.golang.org/protobuf v1.34.1 h1:9ddQBjfCyZPOHPUiPxpYESBLc+T8P3E+Vo4IbKZgFWg=
google.golang.org/protobuf v1.34.1/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v2 v2.2.8 h1:obN1ZagJSUGI0Ek/LBmuj4SNLPfIny3KsKFopxRdj10=
Expand Down
Loading

0 comments on commit 3006333

Please sign in to comment.