Generate API client with OpenApi codegen

A lot of API are documented using Swagger, it’s a good thing that API are documented for us developer for understanding how they work and how to call them.
In this article, I will try my best to help you use this documentation in order to generate a client that will call those API.

What you will need

In order to follow this tutorial, you will need a REST API, so you can :

• Follow those tutorial to built your API, one to documente it and then migrate to openApi

• Having another API documented with openApi 2 ready

Step 1 : importe the api json documentation

The easy part of this tutorial is to import the json documentation of the api you want the first one to call an put it in your ressource folder.
In my exemple I will use my clone API and I have created a Jedi one, so in order for my clone to retrieve the jedi, i will import the jedi documentation file for then generate it’s client

	{
	"openapi":"3.0.1",
	"info":{
	"title":"Jedi API",
	"description":"API for searching jedi across the galaxy",
	"contact":{
	"name":"Erwan LE TUTOUR",
	"url":"https://github.com/ErwanLT",
	"email":"[e-mail]"
	},
	"license":{
	"name":"MIT Licence",
	"url":"https://opensource.org/licenses/mit-license.php"
	},
	"version":"2.0"
	},
	"servers":[
	{
	"url":"http://localhost:8082",
	"description":"Generated server url"
	}
	],
	"paths":{
	"/":{
	"get":{
	"tags":[
	"jedi-controller"
	],
	"summary":"Find all clones",
	"description":"Find all clones present in database.",
	"operationId":"getAllJedi",
	"responses":{
	"200":{
	"description":"found jedis",
	"content":{
	"application/json":{
	"schema":{
	"type":"array",
	"items":{
	"$ref":"#/components/schemas/Jedi"
	}
	}
	}
	}
	},
	"404":{
	"description":"No jedi found"
	}
	}
	}
	}
	},
	"components":{
	"schemas":{
	"Jedi":{
	"required":[
	"name",
	"rank"
	],
	"type":"object",
	"properties":{
	"name":{
	"type":"string",
	"description":"The jedi name",
	"example":"Anakin Skywalker"
	},
	"rank":{
	"type":"string",
	"description":"The jedi rank",
	"example":"Master"
	},
	"padawan":{
	"type":"array",
	"items":{
	"$ref":"#/components/schemas/Jedi"
	}
	}
	}
	}
	}
	}
	}

view raw jedi.json hosted with ❤ by GitHub

Step 2 : Updating our pom.xml

To generate the client we will use the openApi codegen maven pluggin.

To do that we need to update the build part of our pom.xml and add the pluggin.

	<plugin>
	<groupId>org.openapitools</groupId>
	<artifactId>openapi-generator-maven-plugin</artifactId>
	<version>5.2.0</version>
	<executions>
	<execution>
	<goals>
	<goal>generate</goal>
	</goals>
	<configuration>
	<inputSpec>${project.basedir}/src/main/resources/swagger/jedi.json</inputSpec>
	<generatorName>java</generatorName>
	<configOptions>
	<sourceFolder>src/gen/java/main</sourceFolder>
	</configOptions>
	</configuration>
	</execution>
	</executions>
	</plugin>

view raw openApiPluggin.xml hosted with ❤ by GitHub

So let’s see what we have here :

• the goal generate indicate us that the client will be generated during the … generate phase of our build, or can be generated using the maven command mvn generate.

The configuration will hold some option used to customized the generated client like :

• the inputSpec that tell the pluggin where to find your imported file

• the generatorName for the case

• sourceFolder will be were my client will be generated in my ressource folder

You can add some more options, I recommend you to read the README.md of the project to have a better understanding of the possible options and choose those that applies to your case.

Step 3 : Launch a build

Now that we have implemented the pluggin usage, let’s go to clean install our project.
If all goes right you should have in your target folder, something that look like that :

As you can see, at the path described in the pluggin configuration I have my controller JediControllerApi who use ApiClient to call the jedi API and the model described in my documentation Jedi that are generated.

With that I can directly use this object in my project without having to create my own and then do some mapping.

Step 4 : exploring the generated files

If you have carefully read the step 1, in my documentation file, the server url was my localhost using port 8082, so in my ApiClient i will also have a field (basepath) that will have this value

private String basePath = “http://localhost:8082";

By default the generated client will use Okhttp to make the api call, so you may have to add some more dependencies to your pom.xml in order to run your app.

Step 5 : using the client

Now that we have gone all the way through the generation of the client, it will be best to use it don’t you think ?
Nothing really hard here, just declare your generated controller and call it to reach the second API

JediControllerApi jediControllerApi = **new **JediControllerApi();
**return **jediControllerApi.getAllJedi();

Thanks for your reading time, as previously, the code used in this tutorial is findable in this Github repository, branch openApiCodeGen.