Using a custom template for Swagger Codegen with Gradle

This article is the second part of a Swagger Codegen series. If you haven’t read the first one, make sure you do it before continuing. In this one I’ll show you how to use a customized template for code generation and what’s the problem with the standard template.

The problem

Let’s check out what we have in the server generated code with the base template.

As you can see, there is a lot of default implementation for the methods which is not necessary for all the use-cases. getObjectMapper , getRequest , getAcceptHeader  and of course the implementations for the endpoint methods.

Overriding the template to be used

Using a custom template is not complicated at all. It’s just a configuration property for the generator class in the build.gradle. First of all, we have to download the currently used template by Swagger, you can do it by going to the GitHub repository of the code generator and find the templates there for the Spring language.

For the 2.3.1 code generator which we are using, you can find the templates here.

I’ve created a new folder in the contract project called template and copied there all the Spring template files from the Swagger Codegen. Now we have to set the generator to use this new template for code generation.

Let’s define a new property in the build.gradle  which will store the template directory.

Now we can use it for setting the templateDir  property of the CodegenConfigurator  class like the following.

After executing ./gradlew clean build install , everything should stay the same as it was before. We just integrated the copied templates into the code generation process, but we haven’t changed anything yet.

Changing the templates

Basically, the API interface we got after the generation is coming from the apiController.mustache  file. That’s the template for the UserApi  class. Mustache is a very basic templating language, I don’t want to go into details but you can find out more here.

We start by cleaning up the imports first as by default it has some conditional import statements in case of JDK8, BeanValidation library, Async execution, etc. and it has a @Generated  annotation as well which I usually don’t need.

The import looks like the following for me:

Of course if you need less, remove it, if you need more, leave it there.

Now comes the Controller itself. Let’s remove the bunch of default methods and clear out the method for the operations. I like to use delegates for the APIs, so there is the API interface which defines the endpoints and there is a Controller class which has an implementation to call into a Delegate class which has the same methods. In this case it’s possible to add some default functionality into the Controller layer, like checking some user privileges, checking for localization, etc.

Now let’s focus on just clearing it up and we’ll jump back to adding a default functionality. The Controller template looks like this for me:

I switched the @Controller  annotation to be a @RestController  as I only use it for REST APIs and the Delegate will be wired into the Controller via constructor injection.

I also cleaned up the apiDelegate.mustache template which is obviously used for generating the Delegate interface. The final result looks the following:

Last but not least, cleaning up the API interface is necessary as well:

Now as we have the templates cleaned up, let’s jump into the build.gradle  and enable the delegatePattern  property for the generation.

Now after the changes we made, executing the code generation will result in the following classes (at least which are important for now):

  • UserApi  – this is the interface definition for the endpoints as before
  • UserApiController  – this is a basic controller class which implements the endpoints from the interface above and delegates the work to the UserApiDelegate  class
  • UserApiDelegate  – this one is the interface to implement the logic behind the endpoints and it’s called by the controller above

Now, with the new structure, implementing the UserApiDelegate  in the actual service application will result in the following code:

As it’s not a controller anymore, we can simply mark it as a @Component  and it will be picked up by the generated controller.

Just a quick recap, in this part of the series, we saw how to use a custom template for code generation. It’s not a full customization as you can only change the existing templates, you cannot add new ones. Also, we’ve taken a quick look at how the delegate pattern looks. The full code can be found on GitHub.

Give it a try and give me some feedback how you feel about this, in the comments or on Twitter. In the next part we’ll explore more possibilities of the code generator.

4 Replies to “Using a custom template for Swagger Codegen with Gradle”

  1. Great tutorial. I followed the instructions closely, and got it close to working. However, marking my UserApiDelegateImpl with @component is not getting it picked up by the generated controller. Am I missing something?

  2. Hello, thanks for sharing.

    I have a question. Do you know if we need to copy all the template files in our own custom directory? For example, I need to customize only pojo.mustache, and I don’t want to include all the template files in my template directory.

Leave a Reply

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