Generate Models Using OpenAPI With Lombok Annotations

1. Overview

Lombok is a Java library that helps to reduce boilerplate code like getters, setters, etc. OpenAPI provides a property to auto-generate a model with Lombok annotations.

In this tutorial, we’ll explore how to generate a model with Lombok annotations using an OpenAPI code generator.

2. Project Setup

To begin with, let’s bootstrap a Spring Boot project and add the Spring Boot Starter Web and Lombok dependencies:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.1.2</version>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope>
</dependency>

Additionally, we need the Swagger Annotations, Gson, and Java Annotation API dependencies and more to prevent errors related to packages in the generated code:

<dependency>
    <groupId>jakarta.annotation</groupId>
    <artifactId>jakarta.annotation-api</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.19</version>
</dependency>
<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>jackson-databind-nullable</artifactId>
    <version>7.1.0</version>
</dependency>
<dependency>
    <groupId>jakarta.validation</groupId>
    <artifactId>jakarta.validation-api</artifactId>
    <version>3.1.0</version>
</dependency>

In the next section, we’ll create an API specification for a model named Book and later generate the code with Lombok annotation using the OpenAPI code generator.

3. Generating Model Using OpenAPI

The idea of OpenAPI is to write the API specification before actual coding begins. Here, we’ll create a specification file and generate a model based on the specification.

3.1. Creating Model Specification

First, let’s create a new file named bookapi.yml in the resources folder to define the Book specification:

openapi: 3.0.2
info:
  version: 1.0.0
  title: Book Store
  license:
    name: MIT
paths:
    /books:
      get:
        tags:
          - book
        summary: Get All Books
        responses:
          200:
            description: successful operation
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Book'
          404:
            description: Book not found
            content: { }
components:
  schemas:
    Book:
      type: object
      required:
        - id
        - name
        - author
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        author:
          type: string

In the specification above, we define the Book schema with id, name, and author fields. Additionally, we define an endpoint to get all stored books.

3.2. Generate a Model With Lombok Annotation

After defining the API specification, let’s add the OpenAPI plugin to the pom.xml to help generate the code based on the specification:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.7.0</version>
    <executions>
        <execution>
	    <goals>
	        <goal>generate</goal>
	    </goals>
	    <configuration>
	        <inputSpec>${project.basedir}/src/main/resources/bookapi.yml</inputSpec>
		<generatorName>spring</generatorName>
		<configOptions>
		    <additionalModelTypeAnnotations>@lombok.Data @lombok.NoArgsConstructor @lombok.AllArgsConstructor</additionalModelTypeAnnotations>
		</configOptions>
		<generateApis>false</generateApis>
		<generateSupportingFiles>false</generateSupportingFiles>
		<generateApiDocumentation>false</generateApiDocumentation>
                <configOptions>
                    <useJakartaEe>true</useJakartaEe>
                </configOptions>
	    </configuration>
	</execution>
    </executions>
</plugin>

Here, we specify the location of the specification file for the plugin to check during the generation process. Also, we add the additionalModelTypeAnnotations property to add three Lombok annotations to the model.

For simplicity, we disable the generation of supporting files and API documentation.

Finally, let’s generate the Model by executing Maven install command:

$ ./mvnw install

The command above generates a Book model in the target folder.

3.3. Generated Code

Let’s see the generated Book model:

@lombok.Data @lombok.NoArgsConstructor @lombok.AllArgsConstructor

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2024-01-03T22:22:14.557819500+02:00[Europe/Bucharest]")
public class Book {

  private Long id;

  private String name;

  private String author;

  // ..
}

In the generated code above, the three Lombok annotations we defined in the plugin using the additionalModelTypeAnnotations property are added to the model class.

The @Data annotation helps generate the getters, setters, etc., at compile time. The @NoArgsConstructor generates an empty constructor, and the @AllArgsConstructor generates a constructor that takes an argument for all fields in the class.

4. Conclusion

In this article, we learned how to generate a model with Lombok annotation using the OpenAPI code generator. Adding the additionalModelTypeAnnotations property provides us the flexibility to add desired Lombok annotations.