Building REST APIs often involves repetitive tasks such as writing controllers, models, and API interfaces. This boilerplate work can slow development and introduce inconsistencies across projects.
OpenAPI Generator solves this problem by automatically generating API code from OpenAPI specifications. When combined with Spring Boot 3 and Jakarta EE, it becomes a powerful tool for accelerating modern API development.
By customizing OpenAPI Generator templates, developers can enforce mandatory annotations, standard imports, and consistent coding patterns across all generated APIs. This approach not only reduces repetitive work but also improves code quality, maintainability, and development speed.
In this article, you'll learn how to optimize OpenAPI Generator templates to streamline API development in Spring Boot applications.
TL;DR
If you want to generate clean and consistent APIs in Spring Boot 3, OpenAPI Generator with custom templates can automate most of the repetitive work.
With the right template customization you can:
- Automatically generate Spring Boot controllers
- Enforce mandatory annotations
- Standardize imports and validation rules
- Reduce boilerplate code across microservices
This article explains how to customize OpenAPI Generator templates to produce production-ready API code.
OpenAPI Generator Architecture
Before diving into customization, let's understand how OpenAPI Generator fits into the API development workflow.
This workflow ensures that generated APIs automatically follow project standards, including required annotations, imports, and consistent code structure.
The following diagram illustrates how an OpenAPI specification is transformed into production-ready API code using OpenAPI Generator and custom templates.
OpenAPI Spec → OpenAPI Generator → Custom Templates → Generated API Code
🚀 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
🎯Key Takeaways
- Automate API development using OpenAPI Generator
- Customize templates for Spring Boot 3 and Jakarta EE
- Enforce consistent annotations and imports
- Reduce boilerplate code and improve maintainability
🎯 Final Thoughts
Customizing OpenAPI Generator templates ensures:
- Consistent model definitions
- Improved maintainability
- Seamless framework integration
By refining templates, developers can streamline API development while enforcing structured code generation in Spring Boot 3 and Jakarta EE projects.
Top comments (0)