Revolutionize Your API Development: Unleash the True Power of OpenAPI Generator!

Optimizing OpenAPI Generator templates can significantly enhance API development in Spring Boot 3 and Jakarta EE projects. By leveraging custom templates, developers can enforce mandatory annotations and imports, ensuring clean, maintainable code while reducing repetitive work.

🚀 Why Customize OpenAPI Code Generation?

Out-of-the-box OpenAPI-generated models often lack essential annotations and imports required for JSON serialization and Lombok automation. Customizing templates allows developers to:

Maintain consistency across all generated models.
Reduce manual post-processing.
Integrate smoothly with modern frameworks.

🏗 Domain Specification Library (domain-specification-lib)

📌 Overview

The Domain Specification Library (domain-specification-lib) serves as a centralized repository for API specifications and model definitions. It automates Java POJO creation, streamlining API development and ensuring structured interfaces.

🔥 Key Features

Centralized Model Management — Stores API specifications in a structured format.
Automatic Code Generation — Generates Java POJOs and API interfaces from OpenAPI definitions.
Spring Boot 3 & Jakarta EE Ready — Ensures seamless compatibility.
Fine-Tuned OpenAPI Templates — Allows advanced customization for better flexibility.
Validation & Documentation — Supports Swagger-based validation.
Modular Architecture — Multi-module support for scalable development.

⚙️ OpenAPI Generator Customization

🛠 Configuring OpenAPI Code Generation

This project utilizes the OpenAPI Generator Maven Plugin to automate API stub generation and model creation.

    <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>${openapi-generator.version}</version>
        <executions>
            <execution>
                <id>api-code-generator</id> <!-- Unique ID for execution block -->
                <goals>
                    <goal>generate</goal> <!-- Specifies that code generation should be performed -->
                </goals>
                <configuration>
                    <!-- Allows skipping API generation when necessary -->
                    <skip>${api.build.skip}</skip>
                    <!-- Points to the OpenAPI YAML specification -->
                    <inputSpec>${project.basedir}/src/main/resources/${model}-api.yml</inputSpec>
                    <!-- Defines output directory for generated source code -->
                    <output>${project.build.directory}/generated-source/openapi</output>

                    <!-- Uses Spring generator for code generation -->
                    <generatorName>spring</generatorName>

                    <!-- Defines package paths for API and models -->
                    <apiPackage>${model.package}.${model}.${model.version}.api</apiPackage>
                    <modelPackage>${model.package}.${model}.${model.version}.model</modelPackage>

                    <!-- Enables API and Model documentation-->
                    <generateApiDocumentation>true</generateApiDocumentation>
                    <generateModelDocumentation>true</generateModelDocumentation>

                    <!-- Enables API and Model test generation -->
                    <generateApiTests>true</generateApiTests>
                    <generateModelTests>true</generateModelTests>

                    <!-- Uses Spring Cloud library for API generation -->
                    <library>spring-cloud</library>

                    <!-- Ensures OpenAPI spec validation is enforced -->
                    <skipValidateSpec>false</skipValidateSpec>

                    <!-- Ensures OpenAPI spec validation is enforced -->
                    <generateSupportingFiles>true</generateSupportingFiles>

                    <!--<supportingFilesToGenerate>ApiUtil.java</supportingFilesToGenerate>-->

                    <!-- Adds "Api" suffix to generated API interfaces -->
                    <apiNameSuffix>Api</apiNameSuffix>

                    <!-- Points to a custom template directory -->
                    <templateResourcePath>${project.basedir}/../templates/JavaSpring</templateResourcePath>


                    <configOptions>
                        <globalProperties>
                            <!-- Enables OpenAPI debugging -->
                            <debugOpenAPI>true</debugOpenAPI>
                            <!-- Enables operation-level debugging -->
                            <debugOperations>true</debugOperations>
                        </globalProperties>

                        <!-- Uses Java 8 Date library for generated models -->
                        <dateLibrary>java8</dateLibrary>

                        <!-- Disables OpenAPI nullable fields-->
                        <!--<openApiNullable>false</openApiNullable>-->
                        <!-- Enables Delegate pattern in API controllers-->
                        <delegatePattern>true</delegatePattern>

                        <!-- Enables various modern frameworks and specifications -->
                        <useSpringBoot3>true</useSpringBoot3>
                        <useSpringController>true</useSpringController>
                        <useJakartaEe>true</useJakartaEe>

                        <!-- Ensures that API tags are mapped correctly -->
                        <useTags>true</useTags>

                    </configOptions>
                </configuration>
            </execution>
        </executions>
    </plugin>

🔧 Customizing Templates for Enhanced Code Quality

✨ Customization Goals

Each generated model should include:

Mandatory Annotations

@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonIgnoreProperties(ignoreUnknown = true)
//Lombok annotations
@Getter
@Setter
@SuperBuilder
@NoArgsConstructor
@AllArgsConstructor

Mandatory Import

import com.fasterxml.jackson.annotation.*;
import lombok.*;
import lombok.experimental.SuperBuilder;

📍Steps for Custom Template Integration

Step 1: Locate the Right Template For Spring-based projects, navigate to: JavaSpring/ Key templates to modify:
- model.mustache → Handles imports
- pojo.mustache → Defines annotation

Step 2: Define Custom Templates

📄 pojoCustomAnnotations.mustache

// Custom JSON Annotation
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonIgnoreProperties(ignoreUnknown = true)

// Lombok
@Getter
@Setter
@SuperBuilder
@NoArgsConstructor
@AllArgsConstructor

📄 pojoCustomImports.mustache

// Custom Imports
{{#jackson}}
import com.fasterxml.jackson.annotation.JsonTypeName;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonRawValue;
{{/jackson}}

// Lombok
import lombok.*;
import lombok.experimental.SuperBuilder;

🔨 Updating Maven Configuration

Modify pom.xml to reference the custom templates.

<!-- Points to a custom template directory -->
<templateResourcePath>${project.basedir}/../templates/JavaSpring</templateResourcePath>

🛠 Build & Deployment Instructions

📌 Building the Project
```
mvn clean install
```
📌 After building, the generated API models will be available in:
```
target/generated-source/openapi
```