Repository files navigation

Create Ruby clients from a protocol buffer description of an API.

The easiest way to use this generator is to clone the github repo (either atHEAD or at a release tag) and run the generator using the provided command linetool. The following steps describe how do this.

The GAPIC Generator for Ruby is written in Ruby and requires the Ruby runtimeand several related tools.

First, install Ruby, version 3.1 or later, if you have not already done so.This page on theofficial Ruby website includes installation information. We recommend using aRuby version manager such asASDF.

You will need theBundler andToys gems. Install them if you haven't doneso already:

$ gem install bundler$ gem install toys

The generator itself is present in the repohttps://github.com/googleapis/gapic-generator-ruby. Clone it to your localworkstation. The following steps will use it at HEAD, but you can also checkout a recent release tag.

$ git clone https://github.com/googleapis/gapic-generator-ruby.git$cd gapic-generator-ruby

There are submodules in this repo, so you will need to initialize those.

$ git submodule init$ git submodule update

In this section we'll generate a client for theShowcase API, a sample API usedfor demoing and testing GAPIC.

(The following section will demonstrate how to generate a client for a GoogleAPI from theGoogleapis repo.)

The GAPIC Generator uses protobuf files as input. We will obtain the protos forShowcase from its repository on GitHub.

Clone the Showcase repo. For this example, we will assume we are startinginside the gapic-generator-ruby clone directory (see above). We'll move up onedirectory, clone the showcase repo and then moveback into thegapic-generator-ruby directory for subsequent steps.

$cd ..$ git clone https://github.com/googleapis/gapic-showcase.git$cd gapic-generator-ruby

Each client requires a configuration. The Ruby GAPIC Generator can get thisconfiguration from a YAML-formatted config file, or from the BUILD.bazel fileused to generate Google APIs. For Showcase, we have neither, so we'll write aYAML file.

Create a file calledshowcase.yml and copy the following into it:

:transports: ["rest", "grpc"]:gem:  :name: google-showcase

Note that all the keys begin with a colon, which signals to Ruby that theyshould be deserialized as Symbol keys rather than String keys.

We can now run the generator, by using a Toys tool provided in the repo. Thisrun will generate a client of the "Echo" service, one of the services in theShowcase API. It will read the source protos from the gapic-showcase clone,and write the result into atmp directory within the gapic-generator-rubyclone. It will also get the configuration from theshowcase.yml file youcreated above.

Make sure you have moved into the gapic-generator-ruby directory, then run:

$ toys run --input-dir=../gapic-showcase/schema --output-dir=tmp \  --config-file=showcase.yml google/showcase/v1beta1/echo.proto

Now you can see the results in thetmp directory.

$cd tmp$ ls

In this section we'll generate a client for the Natural Language service thatis part of Google Cloud. This will be very similar to the above Showcaseexample, but we will get the input protos and configuration from the googleapisrepository, which is brought into gapic-generator-ruby as a submodule.

Within the gapic-generator-ruby directory, run:

$ toys run --output-dir=tmp --clean google/cloud/language/v2

That's it! The generator's proto lookup defaults to searching the submoduleinshared/googleapis so you do not need to provide--input-dir. It alsofinds its configuration in theBUILD.bazel file colocated with the protos.The--clean flag clears out the oldtmp directory (in case you previouslyhad generated the showcase client there.)

The Ruby GAPIC Generator is maintained internally at Google by the Ruby CloudSDK team. The roadmap is generally driven by the needs of the Google API clientlibraries for Ruby. However, contributions will be considered. Before openinga pull request, please open an issue describing the change that you areproposing; unless it is an obvious or trivial fix, it is best to discuss andget agreement on the change before making it.

The CI runs on GitHub Actions and comprises four types of tests:

• Unit tests for the various components
• Comparative tests against golden outputs
• Functional tests for some golden outputs
• Lint and style checks using rubocop

To run the tests, execute this in the repo:

$ toys ci

Note that the functional tests require Docker because they involve spinning upa temporary service for a generated client to talk to.

If you make changes that result in changes to the generated client code, youwill need to regenerate the golden outputs to match. To do that, run thefollowing in the repo:

$ toys gen

Include both the generator and golden output changes in the same pull request.

Golden outputs are generated from input protos in theshared/googleapissubmodule. Their configurations are provided by YAML files in theshared/config directory. Finally, there is an index of those outputs in theshared/gem_defaults.rb file.

If any of these inputs are modified, or if the submodule is updated, you shouldupdate the "binary inputs" in theshared/input directory. These are binaryencodings of that input and configuration data, used in some tests. To updatethe binary inputs, execute:

$ toys bin

While Google uses this product internally to produce API client libraries, thisgenerator itself is not an official Google product. You can use it to produceyour own clients for Google services or your own, but Google does not provideofficial support for use of this generator.