Repository files navigation

The GAPIC (Generated API Client) Generator auto-generates client libraries in various programming languages for bothgrpc-based APIs and Discovery-document-based APIs. Currently, the followingprogramming languages are supported for grpc-based APIs:

• Java
• Python
• Go
• C#
• Ruby
• Node.js
• PHP

For discovery-based APIs, only Java is supported and its output is not stable yet.

The GAPIC Generator also generates packaging files for proto-generated classes and grpc-generated stubs for Javaand Python. This feature is not yet documented here in detail - the instructions below will work without it.

The GAPIC Generator itself doesn't have a platform restriction (because it is purely Java). Sinceprotoc needs to be used aspart of the code generation process, the platforms are naturally restricted to what protoc supports.

As of release 3.5.1 ofprotoc, below are the known platforms thatprotoc has pre-built binaries for:

• linux-aarch_64
• linux-x86_32
• linux-x86_64
• osx-x86_32
• osx-x86_64
• win32

More platforms are likely supported when building protoc from C++ source.

There are two main ways to generate clients:

1. Build from source and run directly. This is detailed below.
2. Invoke a code generation pipeline throughartman. This takes care of several of the stepsbelow and is not documented here.

1. You need a proto file describing your API. Proto files of existing Google APIs are available atgoogleapis.

• Example:https://github.com/googleapis/googleapis/blob/master/google/cloud/language/v1/language_service.proto

2. You need a yaml file describing certain service values. This is not yet well-documented, but you canfigure out some of the settings by looking at existing files.

• Example:https://github.com/googleapis/googleapis/blob/master/google/cloud/language/language_v1.yaml

3. An active internet connection. The first time you build gapic-generator, it will download Java dependencies overthe network.

1. Generate a descriptor file from the proto (once per API)
2. Run client config generation (once per API)
3. Manually tweak the generated client config
4. Run code generation (once per API x language combination of interest)

Each of these steps are described in more detail below. Note: the instructions assume you are running on aUnix-y system; if you are using Windows, you will need to tweak the steps for yourself.

First, make sure you have theJava 8 JDK installed.

Next, you need to installprotoc if you don't have it yet: seeprotocol-compiler-installation.The pre-built binaries are the easiest. There aren't instructions for installation;you just have to download the correct binaries for your platform and put them on your path.Given a platform ${PROTOC_PLATFORM} and a protoc version ${PROTOC_VERSION}:

1. Download the latest zip file ending in "-${PROTOC_PLATFORM}.zip" fromhttps://github.com/google/protobuf/releases
2. Unzip the file:unzip protoc-${PROTOC_VERSION}-${PROTOC_PLATFORM}.zip -d protoc-${PROTOC_VERSION}
3. Copyprotoc to a location on your$PATH:cp protoc-${PROTOC_VERSION}/bin/protoc /usr/local/bin

Clone the present repository and build API Client Generator:

git clone https://github.com/googleapis/gapic-generator.gitcd gapic-generator./gradlew fatJar

Thegoogleapis/gapic-generator directory will hereafter be referenced as${GAPIC_GENERATOR_DIR}.

Clone the googleapis/googleapis repository (it has some config that is needed):

git clone https://github.com/googleapis/googleapis

Thegoogleapis/googleapis directory will hereafter be referenced as${GOOGLEAPIS_DIR}.

You need to locate/decide on the following before you can generate the descriptor file:

1. The include directory with the proto files bundled withprotoc (from theprotoc setup step).Hereafter, this will be referenced as${PROTOC_INCLUDE_DIR}.
2. Any directories containing protos that your API depends on. For Google APIs defined ingoogleapis, this will be${GOOGLEAPIS_DIR}.
3. The directory containing your proto. Hereafter, this will be referenced as${YOUR_PROTO_DIR}.
4. Your proto file (or files). Hereafter, this will be referenced as${YOUR_PROTO_FILE}.
5. The output file name to contain the descriptor file. Hereafter, this will be referenced as${YOUR_DESCRIPTOR_FILE}.

Run the following command to generate the proto descriptor file:

protoc -I=${PROTOC_INCLUDE_DIR} -I=${GOOGLEAPIS_DIR} -I=${YOUR_PROTO_DIR} \  --include_imports --include_source_info -o ${YOUR_DESCRIPTOR_FILE} ${YOUR_PROTO_FILE}

(Skip this section for Node.js — it loads proto files into memory at runtime.)

You need to locate/decide on the following before you can generate the proto message classes:

1. The output directory to contain the proto files. Hereafter, this will be referenced as${GENERATED_PROTO_DIR}.
2. The language you are generating for. The possible values forprotoc arejava,go,php,ruby,python, andcsharp. Note: Node.js is not present for the reason listed above.Hereafter, this will be referenced as${PROTO_OUTPUT_LANG}.

Run the following command to generate the proto message classes:

mkdir -p ${GENERATED_PROTO_DIR}protoc -I=${PROTOC_INCLUDE_DIR} -I=${GOOGLEAPIS_DIR} -I=${YOUR_PROTO_DIR} \  --${PROTO_OUTPUT_LANG}_out=${GENERATED_PROTO_DIR} ${YOUR_PROTO_FILE}

Generating grpc stubs is language-specific.

Find the path to the grpc plugin (gradle will pull in the dependency if you don't have it already):

./gradlew showGrpcJavaPluginPath

The command will print out the path to the executable. Hereafter, this will be referenced as${GRPC_JAVA_PLUGIN}.

protoc -I=${PROTOC_INCLUDE_DIR} -I=${GOOGLEAPIS_DIR} -I=${YOUR_PROTO_DIR} \  --plugin=protoc-gen-grpc=${GRPC_JAVA_PLUGIN} \  --grpc_out=${GENERATED_PROTO_DIR} ${YOUR_PROTO_FILE}

TODO

You need to locate/decide on the following before you call config generation:

1. The service yaml file, hereafter referenced as${YOUR_SERVICE_YAML}.
2. The file name of your output client config file. Hereafter, this will be referenced as${YOUR_CLIENT_CONFIG}

Run the following command to generate the client config:

cd ${GAPIC_GENERATOR_DIR}java -cp build/libs/gapic-generator-*-fatjar.jar \  com.google.api.codegen.GeneratorMain GAPIC_CONFIG \  --descriptor_set=${YOUR_DESCRIPTOR_FILE} --service_yaml=${YOUR_SERVICE_YAML} \  -o=${YOUR_CLIENT_CONFIG}

You can safely ignore the warning about control-presence.

The generated client config containsFIXME comments with instructions on how to choose valuesin the client config. The client config should work as is, though; tweaks are only necessary to improvethe quality of the generated output.

You need to locate/decide on the following before you create the package metadata config file:

1. The output file to contain the packaging config for your client generation. Hereafter, this will bereferenced as${PACKAGING_CONFIG}.
2. The short name of your API, which typically does not include the major version. For example, Cloud Language v1's short nameislanguage. Hereafter, this will be referenced as${API_NAME}.
3. The API major version. The first major version will typically bev1. Hereafter, this will be referenced as${API_VERSION}.
4. The organization name of the API. This would typically include the company name. For example,Cloud Language's organization name isgoogle-cloud. This is used for the full artifact name.Hereafter, this will be referenced as${ORGANIZATION_NAME}.
5. The proto path, which is the proto's package with dots converted to slashes. For example, Cloud Language v1'sproto path isgoogle/cloud/language/v1. Hereafter, this will be referenced as${PROTO_PATH}.

Add the following lines to the ${PACKAGING_CONFIG} file:

artifact_type: GAPICproto_deps:- google-common-protosapi_name: ${API_NAME}api_version: ${API_VERSION}organization_name: ${ORGANIZATION_NAME}proto_path: ${PROTO_PATH}

You need to locate/decide on the following before you call code generation:

1. Your target language, which can be one ofjava,go,php,ruby,nodejs,python, orcsharp.Hereafter, this will be referenced as${LANGUAGE}.
2. The output directory for your generated client classes. Hereafter, this will be referencedas${GENERATED_CLIENT_DIR}.

java -cp build/libs/gapic-generator-*-fatjar.jar  \  com.google.api.codegen.GeneratorMain LEGACY_GAPIC_AND_PACKAGE \  --descriptor_set=${YOUR_DESCRIPTOR_FILE} --service_yaml=${YOUR_SERVICE_YAML} \  --gapic_yaml=${YOUR_CLIENT_CONFIG} --language=${LANGUAGE} \  --package_yaml2=${PACKAGING_CONFIG} --o=${GENERATED_CLIENT_DIR}

The generated client library code will appear in${GENERATED_CLIENT_DIR}.

You can safely ignore the warning about control-presence.

Special note for java: several files will be dumped into the parent directory of${GENERATED_CLIENT_DIR}:

• gradle/
• gradlew
• gradlew.bat

(There is an open issue to fix this:#1918 )

The fixes here are language-specific.

Copy the proto-generated classes into the client directory tree:

cp -r ${GENERATED_PROTO_DIR}/* ${GENERATED_CLIENT_DIR}/src/main/java

In${GENERATED_CLIENT_DIR}/build.gradle, there are a couple dependencies that need to be removed if youare bundling your proto-generated classes and grpc stubs in the same package as the client. They have acomment starting with "// Remove this line if you are bundling". Warning: If you regenerate again, you willneed to remove the lines from the build.gradle file again. (There is an open issue to fix this:#1917 ).

Copy the proto files into the correct subdirectory of${GENERATED_CLIENT_DIR}.(Exact instructions to be added later.)

TODO