Using the OpenAPI generator with Spring Boot

An OpenAPI generator is a tool that automatically generates client and server code based on an OpenAPI specification file. OpenAPI, formerly known as Swagger, is a specification for building APIs.

There are several reasons why we need an OpenAPI generator:

1. Consistency: An OpenAPI generator helps maintain consistency between the API documentation and the code. By generating the code from the OpenAPI specification, developers can ensure that the code accurately reflects the API documentation.
2. Time-saving: Writing code manually can be time-consuming and error-prone. An OpenAPI generator can save time and reduce the risk of errors by generating the code automatically.
3. Flexibility: An OpenAPI generator can generate code in various programming languages, making it easy to integrate with different systems and platforms.
4. Accessibility: An OpenAPI generator can make it easier for developers who are not familiar with the API to start working with it. By generating client code, developers can quickly understand how to interact with the API.

Our next steps will cover the whole scenario.

1. Add the below dependency to the pom.xml file.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>8.0.0.Final</version>
</dependency>
<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>jackson-databind-nullable</artifactId>
    <version>0.2.6</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

2. The OpenAPI specification (open-api.yaml) file, which is typically written in YAML or JSON format, is required by an API generator to generate the code. You need to place this yaml file inside the resources.

This file describes the structure of the API, including endpoints, operations, parameters, request and response payloads, authentication, and other essential details.

OpenAPI specification file

The sample content of the specification file is as follows:

openapi: 3.0.3 # version of the specification
info:
  version: '1'
  title: Open API Generator Spring Boot Example

servers:
  - url: http://localhost:8080

paths:
  /parents:
    get:
      summary: return parents information
      operationId: getParents
      responses:
        200:
          description: General parents information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParentResponse'

components:
  schemas:
    ParentResponse:
      discriminator:
        propertyName: ParentResponseType
        mapping:
          Parent: '#/components/schemas/Parent'
      type: object
      properties:
        status:
          type: string
        errorMessage:
          type: string
      description: Response of the parent.

    Parent:
      allOf:
        - $ref: '#/components/schemas/ParentResponse'
        - type: object
          properties:
            parentId:
              type: integer
              description: The ID of the parent
              format: int64
            parentName:
              type: string
              example: 'Stephen'

From the specification file above, I have addressed the concept of inheritance (parent-child relationship) as it allows common properties and definitions to be reused across multiple API specifications.

3. Most important step, the OpenAPI generator plugin provides additional functionality and customization options for the code that is generated by the OpenAPI generator.

Add the following plugin inside the build tag of the pom.xml file.

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.1.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <id>buildApi</id>
            <configuration>

                <!-- specify the location of specification file here -->
                <inputSpec>${basedir}/src/main/resources/open-api.yaml</inputSpec>
                
                <generatorName>spring</generatorName>
                <generateApis>true</generateApis>
                <generateModels>true</generateModels>

                <configOptions>
                    <generateSupportingFiles>true</generateSupportingFiles>
                    <library>spring-boot</library>
                    <interfaceOnly>true</interfaceOnly>
                    <useBeanValidation>true</useBeanValidation>
                    <sourceFolder>/src/main/java</sourceFolder>
                    <implFolder>/src/main/java</implFolder>
                    <serializableModel>true</serializableModel>
                    <java8>true</java8>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

When the OpenAPI specification file is provided to an API generator, it uses this file to generate code that conforms to the specification. The generator can generate client code, server code, or both, depending on the specific use case.

After you build the project you can see the following classes inside the target folder.

References: https://openapi-generator.tech/docs/installation

Happy coding :)