gen-go-sample

README

Sample Generator for Go API Clients

A generator for samples showing how to make API calls with clients generated by gapic-generator-go.

Prerequisites

• proto descriptors of an API
• sample configurations
• gapic config*

Note: The gapic config is necessary to convey information about resource names and longrunning operations. There is currently work in progress to make the sample generator consume protobuf annotations instead of gapic config. After the work is finished, gapic config will no longer be needed.

Refer to sample config spec for how to config a sample.

Installation

go get github.com/googleapis/gapic-generator-go/cmd/gen-go-sample

Or to install from source:

git pull https://github.com/googleapis/gapic-generator-go.git
cd gapic-generator-go
go install ./cmd/gen-go-sample

Invocation

Run sample generator as a standalone program

gen-go-sample \
  -clientpkg 'url/to/client/pkg;name' \
  -gapic 'path/to/gapic/config/some_gapic.yaml' \
  -o [OUTPUT_DIR] \
  -desc 'path/to/proto/descriptor.desc' \
  -sample path/to/sample.yaml \
  -sample path/to/another_sample.yaml

Or to generate the descriptor files on the fly, run

gen-go-sample \
  -clientpkg 'url/to/client/pkg;name' \
  -gapic "path/to/gapic/config/some_gapic.yaml" \
  -o [OUTPUT_DIR] \
  -desc <(protoc -o /dev/stdout --include_imports -I "$COMMON_PROTO" -I a.proto b.proto)
  -sample path/to/sample.yaml \
  -sample path/to/another_sample.yaml \

• The $COMMON_PROTO variable represents a path to the googleapis/api-common-protos directory to import the configuration annotations.
• The -o flag is necessary because we need to know where generated files will live.

For example, to generate all the samples for the language API, run

export GOOGLEAPIS=/tmp/googleapis
git clone git@github.com:googleapis/googleapis.git $GOOGLEAPIS

export COMMON_PROTO=/tmp/common-protos
git clone git@github.com:googleapis/api-common-protos.git $COMMON_PROTOS

for sample in $GOOGLEAPIS/google/cloud/language/v1/samples/*.yaml
do
  samples+=('-sample')
  samples+=($sample)
done

gen-go-sample \
  -clientpkg 'cloud.google.com/go/language/apiv1;language' \
  -gapic "$GOOGLEAPIS/google/cloud/language/v1/language_gapic.yaml" \
  -o /tmp/language/samples/v1 \
  -desc <(protoc -o /dev/stdout --include_imports -I "$COMMON_PROTO" "$GOOGLEAPIS"/google/cloud/language/v1/*.proto) \
  ${samples[@]}

Run sample generator as an add-on of the client library generator

The sample generator also works as an add-on of the client library generator. All you need to do to enable sample generation is passing sample configurations and gapic config (for the time being) to the generator.

When executing the client library generator as a protoc plugin, run

$ protoc -I $API_COMMON_PROTOS \
  --go_gapic_out [OUTPUT_DIR] \
  --go_gapic_opt 'go-gapic-package=package/path/url;name' \
  --go_gapic_opt 'sample=path/to/sample/config.yaml,sample=path/to/another/sample/config.yaml' \
  --go_gapic_opt 'gapic=path/to/gapic/config.yaml' \
  a.proto b.proto

When executing the client library generator in a docker container, run

$ docker run \
  --rm \
  --user $UID \
  --mount type=bind,source=</abs/path/to/protos>,destination=/in,readonly \
  --mount type=bind,source=</abs/path/to/configs>,destination=/conf,readonly \
  --mount type=bind,source=$GOPATH/src,destination=/out/ \
  gcr.io/gapic-images/gapic-generator-go \
  --go-gapic-package "github.com/package/import/path;name" \
  --sample "path/to/sample/config.yaml" \
  --sample "path/to/another/sample/config.yaml" \
  --gapic "path/to/gapic/config.yaml"