OpenAPI Generator Contribution Quickstart - RingCentral Go SDK

Published in

RingCentral Developers

6 min readJul 19, 2018

I maintain a Go SDK for RingCentral and a few people have asked how they can contribute. Because this is an auto-generated SDK using RingCentral’s OpenAPI / Swagger spec, contributing is a bit different than for hand-built libraries. This article covers my approach to making changes and contributing them back to the OpenAPI Generator project used to generate the SDK. I’ve had 19 pull requests merged, 11 specifically for the Go SDK generator, so this process is working pretty smoothly.

OpenAPI Generator is a community fork of the popular Swagger Codegen project for auto-generating SDKs from an OpenAPI 3.0 or 2.0 spec. I started the Go SDK with Swagger Codegen and filed some issues there but by the time I got around to filing a pull request, the project had been forked and all the Go contributors had moved, so I moved as well.

A benefit of OpenAPI Generator is that the project is moving fast. Since it’s initial release, 3.0.0, on June 1, 2018, it’s already had 5 releases in 5 weeks so getting changes in can see quick turnaround. I’m now also on the Technical Committee for Go. The quick turnaround in review, merging, and releases makes the project great to work with.

TL;DR

This is basically the text I use for contributing to the Go generator. I keep this open in my editor, and copy and paste these lines often. Use the following steps to build your own openapi-generator-cli.jar to build your own SDK.

Afterwards, I’ll walk through each of these commands and provide more info as well.

Pre-requisites include the following:

Read openapi-generator/README.md
Read openapi-generator/CONTRIBUTING.md
Install Java per the README
Install Maven per the README
Fork the repo so you can contribute easily

1.1) Modifying the Generator and Building Your Own SDK

You can modify the generator by editing the files of interest. The Go template files are in this directory:

1.2) Creating a Pull Request

I have a strong preference for submitting changes upstream to the project so I don’t have to maintain them separately in a fork. Here are the quick steps to submit a Pull Request:

Then create a pull request to the correct branch.

Walkthrough for Your Custom SDK

Here I’ll go through each of the major steps.

2.1) Clone the Repo

First fork the repo. This way you can easily contribute your changes to the project after you’re satisfied with them. Then clean and change directory as follows. Many of the commands require you to be in the top level ./openapi-generator directory so you’ll be able to run many commands from that location.

$ git clone https://github.com/<your-name>/openapi-generator
$ cd openapi-generator

2.2) Make Your Changes

Create a branch using git checkout -b <your-change> for your changes. If you want to contribute changes, it’s good to have one branch for each change. According to CONTRIBUTING.md “Smaller changes are easier to review”.

$ git checkout -b go/client/<your-change>
$ vi <files-you-want-to-change>

Here I use vi <files-you-want-to-change> to indicate editing your files but you can use any editor you want. There are two sets of files that are relevant for updating the Go generator, the Mustache templates and the Java helper files. You can find these files here:

Mustache Templates

There is a mustache template for each type of file to be generated including api.mustache, model.mustache, and client.mustache.

modules/openapi-generator/src/main/resources/go

Java Classes

There are two Java classes, though so far I’ve only updated one: AbstractGoCodegen.java and GoClientCodegen.java. These are located here:

modules/openapi-generator/src/main/java/ \
org/openapitools/codegen/languages

2.3) Build the JAR and Your SDK

The JAR is essentially your executable here. Using java -jar path/to/jarfile is like calling the JAR as a command line (CLI) utility. You can build the JAR with mvn clean package from the openapi-generator top level directory and the call the JAR as follows:

$ mvn clean package
$ cd modules/openapi-generator-cli/target
$ java -jar openapi-generator-cli.jar help
$ java -jar openapi-generator-cli.jar config-help -g go
$ java -jar openapi-generator-cli.jar generate -g go \
    -i path/to/openapi-spec.yaml -o path/to/client-dir

Walkthrough for Contributing Your Changes

Once you are satisfied with your changes, it’s time to contribute them to your changes.

3.1) Creating and Testing the Petstore SDK

Whenever you contribute a change, it’s important to update the Go Petstore client SDK. This will allow the CI to test the output of your changes and allow the team to review it as well. Use the following steps to create and test the Petstore SDK.

$ bin/go-petstore.sh
$ mvn verify -f samples/client/petstore/go

This will allow you to run all the tests in that directory in the *_test.go files. Running the tests specifically against the Go Petstore client will allow you to quickly verify your changes are working. Some of the tests can fail intermittently due to no reason of your own code including TestFindPetsByTag. Don’t worry about these and feel free to continue.

3.2) Verify All Code

To verify all code, run the following:

$ mvn verify

When everything is working you will see the following near the end of the log.

[INFO] -------------------------------------------------------------[INFO] BUILD SUCCESS
[INFO] -------------------------------------------------------------

The commit your code before running ensure-up-to-date.

$ git add *
$ git commit -m 'my changes'
$ bin/utils/ensure-up-to-date

You should commit your changes before you run ensure-up-to-date because it may generate additional files that you need to commit before filing a PR. You could manually identify files to commit, but if you know your files are good, it’s easier to commit them separately.

ensure-up-to-date builds a number of samples to check if your changes affect other generators, potentially generating many other files that need to be committed to your branch. If no other code has been changed, you will see Git working tree is clean in the following and you’re ready to push and create a pull request.

$ bin/utils/ensure-up-to-date
# START SCRIPT: bin/utils/ensure-up-to-dateIMPORTANT: this script should be run by the CI (e.g. Shippable) to ensure that the 'samples/' folder is up to date.Please press CTRL+C to stop or the script will continue in 5 seconds.Git working tree is clean

If there are changes, you will see the following after which you will need to add the files and run ensure-up-to-date again.

Perform git status
On branch spec/enhance/add-petstore-3.0-native-specChanges not staged for commit:(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)modified:   samples/server/petstore/kotlin-server/ktor/.openapi-generator/VERSIONno changes added to commit (use "git add" and/or "git commit -a")
Please run 'bin/utils/ensure-up-to-date' locally and commit changes (UNCOMMITTED CHANGES ERROR)

When you commit these changes, I like to use a commit message that begins with update samples to indicate they are general samples, not part of the core changes that need to be reviewed.

$ git add *
$ git commit -m 'update samples'

3.3) Push Your Changes and Create a Pull Request

Now you can push your changes to your branch and create a pull request:

$ git push origin go/client/<your-change>

Once your Pull Request has been created, you can wait for comments or improve it. To improve your pull request, simply make your changes and follow this process, pushing your changes to your branch. Then they will automatically get added to your Pull Request.

When you’re ready to go, you will see something like the following. If you have some build failures, examine the logs. Sometimes you will need to fix something in your code and sometimes the failures aren’t related to your code. If it’s the latter, you can look to figure it out or rest easy and wait for the reviewers to take a look.

Extras

To run this, you need to have Java and Maven installed. The following commands can get this set up for you on OS-X.

$ brew cask intall adoptopenjdk12
$ export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-12.0.2.jdk/Contents/Home/
$ brew install maven

Summary

Creating Pull Requests for the OpenAPI Generator Go client is straight-forward after doing it a few times. Try it out and you’ll get good and fast at it. If you have any questions, please post here, or on the GitHub issues for OpenAPI Generator or the RingCentral Go SDK.