Generating stubs with Swagger Codegen and Gradle

Introduction to Swagger

Swagger is a powerful tool to enable sharing REST contracts with each other. It’s useful in any architecture today and even better if you are thinking about integrating with a 3rd party service. I think everyone was in the situation that developers have to agree in certain HTTP endpoints, naming, parameters, methods, response types, response codes, etc. Even when there is a consensus, how people share the agreement? In a Word document? In an email? Sure, it’s working fine as well but there is another, formalized possibility to do this which is Swagger contract.

Swagger contract is a tool which implements the OpenAPI specification which is essentially giving you a language to describe your API in a standard way and it also gives you a couple of other things like an API editor, code generator, etc.

Example API

Consider the following API for a user management service. I’m keeping it as simple as possible with two endpoints, one for getting the list of users and one for creating a new user.

The endpoint is located at /user  and two methods are supported, GET and POST. It’s specified which MIME types are supported for which one and the incoming parameters are also defined along with the return type of the API. I’m not going into much details, but if you are interested, take a look at swagger.io.

Introduction to Swagger Codegen

Simply just describing the API has a very big advantage because now people have a common language to read and write APIs. What could be even better, if you can generate some code from the API description to avoid the boilerplate code for each and every endpoint you want to call or implement. Let’s assume you want to have a server for the API I showed but you don’t want to manually define all the mappings and all the other stuff but you want to have the base code ready just by using the Swagger contract.

Fortunately, this is where Swagger Codegen comes into the picture as it’s specifically doing code generation from a contract. You can use Swagger Codegen easily via CLI, Maven, as well as other ways.

You just have to provide a couple of information for the generator and voila, you have the stubs. This basic info is, the input file, output directory, the language you want to use the stub for and after these, only customization is left.

Using the generator in Gradle is not that simple but I have to say it’s not that difficult either, let’s check it out.

Swagger Codegen with Gradle

First, starting with just generating the server-side stub for the contract. We’ll need an empty Gradle project which means a build.gradle  and a settings.gradle  file and of course optionally a Gradle wrapper.

My project has the build.gradle  and the settings.gradle , additionally I have Gradle wrapper and I’ve put the Swagger contract file into the api  folder, named swagger.yml.

Let’s take a look at the project structure, defined in the settings.gradle

We’ll have a subproject, called user-service-server which will be just a placeholder to refer from the buildscript. Now let’s see how the build.gradle  looks like.

First of all, the buildscript is depending on the Swagger Codegen as we’ll invoke classes directly from it and of course Maven Central is necessary as well.

Now the base plugin will be applied as we need the base tasks, like cleaning up the build directory. Group is just the groupId and the 2 imports are important as these classes will be used in the buildscript to trigger the code generation. Now we can define the basics for the generated subproject, user-service-server.

At the beginning, it’s just a standard Gradle project with Java and Maven plugins. Then the build directory of the subproject is overwritten, for example in case of user-service-server, it will be user-service-contract/build/user-service-server. The last thing is to generate a JAR file with the sources.

I defined a couple of properties in advance also for the generator.

Now the tricky part comes, the actual generation. Here, we can simply refer to the subproject we defined in the settings.gradle  and execute the generation inside of it.

What’s important here is that we’re defining the dependencies for the generated sources, in this particular case, we’ll need Spring MVC (for this I used spring-boot-starter as it contains everything which we need) and springfox for the Swagger annotations.

Then a special task is defined to generate the server-side of the contract. There are plenty of configuration possibilities, here I defined only the basics like the language to use, the packages and some additional, language specific properties. After we’re done with the configuration, we’ll execute the generation with the DefaultGenerator  class by invoking the generate method.

In order to execute it before the compilation process – as Swagger generates only the sources of course – I wired in the generateServer  task right before the compileJava  task.

Executing ./gradlew clean build install  will generate the interfaces and the models from the Swagger API under the user-service-contract/build/user-service-server/libs folder in JAR format, along with the sources. Also a pom.xml  is generated under the poms folder. Having the install  task as well will simply put the artifacts into the Maven local repository. This is necessary as we want to use them for the actual service.

Let’s take a deeper look into the generated files. Under the src/main/java/com/arnoldgalovics/blog/userservice/api folder, a UserApi.java  is generated which has the defined endpoints from the Swagger contract. It has the proper Spring MVC annotations and it has some template implementation as well with some other default methods.

Under the model package, we have the generated models for the responses and for the requests. They are simple POJOs with a couple of jackson annotations, setters, getters. For example UserResponse.java  looks like this

Using the generated sources

Now as we have the artifacts ready to be used in the Maven local repository, let’s start with a new project which will use the generated code. I’ll create a Gradle project here as well just to stick with the same build tool but it doesn’t really matter. I’ve created a project called user-service and this is how the build.gradle  looks like:

Completely standard setup for a Spring Initializr project, the only important thing here is that it’s configured to use the Maven local repository and as a dependency, it’s using the generated artifacts. After importing the project to your favorite IDE, we can access the generated API interface and can create the following UserApiController  class.

Here, as you can see it’s implementing the generated UserApi  interface which defines the endpoints.

Now we are ready to start the application including the endpoints that are defined by the Swagger API.

The full project is available on my GitHub. If you enjoyed the article, share it and let me know your thoughts on it in comments or on Twitter.

2 Replies to “Generating stubs with Swagger Codegen and Gradle”

Leave a Reply to Dapei Jiang Cancel reply

Your email address will not be published. Required fields are marked *