Generating Java Code from OpenAPI Specs with Gradle: A Practical Guide

Integrating external services often involves working with APIs documented using the OpenAPI specification (formerly Swagger). Manually creating client code, Data Transfer Objects (DTOs), and configuration can be time-consuming and error-prone. Fortunately, tools exist to automate this process. This guide explores how to use the OpenAPI Generator Gradle plugin to streamline the generation of Java code directly from an OpenAPI definition within a Gradle project.

Adding the OpenAPI Generator Plugin

The first step is to incorporate the OpenAPI Generator plugin into the Gradle build file (typically build.gradle.kts or build.gradle). Add the plugin ID and version to the plugins block:

plugins {
    id("java-library") // Or your specific Java plugin
    id("org.openapi.generator") version "7.12.0" // Use the desired version
}

Configuring the Generator Task

With the plugin added, configuration is necessary to tailor the code generation process. This is done within the openApiGenerate block in the build script:

openApiGenerate {
    generatorName.set("spring") // Specifies the target framework/language
    inputSpec.set("$projectDir/src/main/resources/openapi/your-api-spec.yaml") // Path to the OpenAPI definition file
    outputDir.set("${layout.buildDirectory.get()}/generated") // Destination for generated code
    validateSpec.set(true) // Enable validation of the OpenAPI spec

    // Define the package for generated model classes (DTOs)
    modelPackage.set("com.yourcompany.yourproject.model")
    generateModelDocumentation.set(false) // Optional: disable documentation generation for models

    // Set specific configuration options for the chosen generator
    configOptions.set(
        mapOf(
            "dateLibrary" to "java8",           // Use Java 8 date/time types (LocalDate, LocalDateTime)
            "useJakartaEE" to "true",         // Use jakarta.* namespace instead of javax.*
            "useRuntimeException" to "true",  // Generate methods throwing runtime exceptions
            "useSpringBoot3" to "true"          // Enable Spring Boot 3 specific adjustments
        )
    )
}

Let’s break down these configuration properties:

• generatorName: This critical setting determines the type of code generated. Setting it to "spring" targets Spring framework conventions. Other generators exist for different languages and frameworks (e.g., java, jaxrs-spec, kotlin-spring).
• inputSpec: Provides the path to the OpenAPI specification file (can be YAML or JSON). Ensure this path correctly points to your API definition.
• outputDir: Specifies the directory where the generated source code will be placed. Using the build directory is common practice.
• validateSpec: Setting this to true ensures the plugin checks the validity of the OpenAPI specification before attempting generation, preventing errors caused by malformed specs.
• modelPackage: Defines the Java package for the generated DTOs or model classes. If only models are required (and not API client interfaces or controllers), specifying apiPackage might not be necessary.
• generateModelDocumentation: Controls whether documentation comments derived from the OpenAPI spec are added to the generated models.
• configOptions: Allows fine-tuning the generated code based on the chosen generatorName.
  • dateLibrary = "java8": Ensures modern Java date/time types (java.time.LocalDate, java.time.LocalDateTime) are used instead of older types.
  • useJakartaEE = "true": Essential for modern Java applications (especially Jakarta EE 9+ and Spring Boot 3+), instructing the generator to use the jakarta.* package namespace instead of the legacy javax.*.
  • useRuntimeException = "true": Configures generated API client methods (if generated) to throw unchecked (runtime) exceptions rather than checked exceptions.
  • useSpringBoot3 = "true": Crucial when working with Spring Boot 3.x. It ensures compatibility by using the correct namespace (jakarta.*) and aligning dependencies and code structure with Spring Boot 3 requirements.

Integrating Generation into the Build Process

To ensure the code is generated automatically before compilation, configure the compileJava task to depend on the openApiGenerate task:

tasks.named<JavaCompile>("compileJava") {
    dependsOn(tasks.named("openApiGenerate"))
}

This setup guarantees that whenever the Java code is compiled (e.g., during a build task), the OpenAPI generation task runs first, providing the necessary source files.

Including Generated Code in Compilation

The generated code resides in the specified outputDir, which might not be part of the default source sets recognized by the Java compiler. To include these generated sources, modify the sourceSets configuration:

sourceSets {
    main {
        java {
            // Add the directory containing the generated Java source files
            srcDir("${layout.buildDirectory.get()}/generated/src/main/java")
        }
    }
}

This snippet adds the standard output path for generated Java sources to the main source set, making the generated classes available for compilation and use within the project.

Bonus Tip: Inspecting Source Sets

For those new to Gradle or needing to verify the source set configuration, a simple task can be registered to print the details:

tasks.register("printSourceSetInfo", DefaultTask::class) {
    // Capture source set information during configuration phase
    val sourceSetInfo = (project.extensions.getByName("sourceSets") as SourceSetContainer)
        .associate { sourceSet ->
            sourceSet.name to sourceSet.allSource.srcDirs.map(File::getAbsolutePath)
        }

    doLast { // Execute during the execution phase
        println("Current Project Source Sets:")
        sourceSetInfo.forEach { (name, srcDirs) ->
            println("SourceSet: $name")
            if (srcDirs.isEmpty()) {
                println("  -> (No source directories)")
            } else {
                srcDirs.forEach { dir ->
                    println("  -> $dir")
                }
            }
        }
    }
}

Running ./gradlew printSourceSetInfo will display all configured source sets and their associated directories, helping confirm that the generated code path is correctly included.

By implementing these steps, developers can effectively leverage the OpenAPI Generator Gradle plugin to automate the creation of Java code from OpenAPI specifications, reducing boilerplate, ensuring consistency, and accelerating the integration process with external APIs in Gradle-based projects.

At Innovative Software Technology, we excel in streamlining complex software development workflows. Integrating tools like the OpenAPI Generator within Gradle is fundamental to our approach for building efficient, maintainable Java and Spring Boot applications. Our expertise in API integration and automated code generation ensures your projects benefit from reduced development time and enhanced code quality. If you’re looking to optimize your build processes, seamlessly integrate with OpenAPI-documented services, or require custom software development solutions, partner with Innovative Software Technology. We provide expert guidance and implementation services to accelerate your API strategy and empower your development teams.