Tech Blog

Customizing Swagger Codegen Client SDKs

In a previous blog post, we described how to use the Swagger Codegen toolset to build full client SDKs for the Alma APIs. In this post, we’ll show how to customize the output of the tool to fit the needs of your workflow. Specifically, we’ll perform the following tasks:

  • Download and build the source of the CodeGen tool
  • Customize the package names of Java generated code
  • Customize the generated Java models

Download and build

To get started, we’ll follow the Getting Started instructions  in the CodeGen repository.

$ git clone https://github.com/swagger-api/swagger-codegen
$ cd swagger-codegen
$ git checkout 3.0.0
$ mvn clean package

Now you can run the help command to get a list of supported options:

$ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -h 
usage: swagger-codegen generate [-h] [-v []] [-l] [-o] [-i] [-t] [--template-version] [--template-engine] [-a] [-c] [-D [ [ ...]]] [-s] [--api-package]
....

Customize Java package names

We can now add some customization to the affect the generated code. To learn what configuration options are available, run the following:

$ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l java
CONFIG OPTIONS
	sortParamsByRequiredFlag
	    Sort method arguments to place required parameters before optional parameters. (Default: true)
...

We’ll build a small configuration file with some properties, including the names of the model and API packages:

{
  "modelPackage": "com.exlibrisgroup.alma.models",
  "apiPackage": "com.exlibrisgroup.alma.apis",
  "serializableModel": true,
  "library": "jersey2",
  "additionalProperties": {
    "dateLibrary": "java8"
  }
}

Now we’re ready to generate our SDK using the options file we defined above:

$ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
-i https://developers.exlibrisgroup.com/wp-content/uploads/alma/openapi/users.json \
-l java \
-o ~/java-client \
-c ~/options.json \
--resolve-fully
The resolve-fully flag is required to process the OpenAPI definitions provided by Alma.

We can now follow the instructions in the previous blog post to compile and run this sample Java file which uses the code we just generated. (Make sure you have an ALMA_APIKEY environment variable defined.)

$ cd java-client
$ mvn clean package
$ cd .../
$ javac -cp ".:java-client/target/swagger-java-client-1.0.0.jar:java-client/target/lib/*" GetUser.java
$ java -cp ".:java-client/target/swagger-java-client-1.0.0.jar:java-client/target/lib/*" GetUser joshw

Unfortunately, we get the following error:

Exception in thread "main" java.lang.IllegalArgumentException: Unrecognized field "scope" (class com.exlibrisgroup.alma.models.Parameter2), not marked as ignorable (2 known properties: "value", "type"])

This seems to indicate that the Alma API has delivered a field that is not defined in our model. This is not ideal behavior as we’d prefer that our client simply ignore any unknown properties. In order to accomplish that, we’d like to include the @JsonIgnoreProperties attribute in the model classes. Happily we can modify the templates used to generate the models.

Customize the generated Java models

The Swagger CodeGen uses mustache templates to define how the code is generated. We can copy the files in this repository to our local environment. Then in the pojo.mustache file, we add this declaration to the top of the file:

{{#jackson}}
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
{{/jackson}}

and this attribute before the public class:

@JsonIgnoreProperties(ignoreUnknown = true)

Then we can re-run our code generation from the previous step, adding a -t argument which points to our customized template folder:

$ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
-i https://developers.exlibrisgroup.com/wp-content/uploads/alma/openapi/users.json \
-l java \
-o ~/java-client \
-c ~/options.json \
--resolve-fully \
-t ~/templates

We’ll follow the instructions above to build the package. Now when we run our code, we see that the unknown properties are ignored and we get the expected result:

$ java -cp ".:java-client/target/swagger-java-client-1.0.0.jar:java-client/target/lib/*" GetUser joshw
Retrieved details for Josh Weisman

There are many options for customizing the code generated by these tools. Hopefully this post provides a good starting point for you to explore further.

Leave a Reply