oap-gradle :: openapi-processor

openapi-processor-gradle

a Gradle plugin based on the openapi-processor-api to handle any openapi-processor without an explicit dependency on the processor.

plugin version	minimum gradle version	minimum java version
2025.x	8.2+ with kotlin dsl 7.2+ with groovy dsl	17
2022.x, 2023.x	7.0+
2021.3	6.5 with kotlin dsl 5.5+ with groovy dsl

plugin version

minimum gradle version

minimum java version

2025.x

8.2+ with kotlin dsl
7.2+ with groovy dsl

2022.x, 2023.x

7.0+

2021.3

6.5 with kotlin dsl
5.5+ with groovy dsl

In case the generated source should be formatted with google code format, it is necessary to configure a few additional jvm parameter to make google code format work when running the processor with JDK 16+.

gradle dsl

An openapi-processor-spring spring specific description is available in Gradle Integration.

The plugin adds a new configuration block openapiProcessor to the Gradle project. Each processor is configurable by a nested configuration block.

Apart from that there are only two options that are recognized inside the configuration block:

apiPath, which defines the path to the openapi YAML file. This is usually the same for all processors and placing it directly into the openapiProcessor block sets it for all processors.
checkUpdates, which allows to enable a version check for the Gradle plugin itself and any processor that supports a version check. It can have one of 3 values:
- never, this is the default and disables all update checks.
- daily, this will check once a day if there is a newer version available. The plugin remembers the last check by writing a timestamp to build/openapiprocessor/<processor>.yaml. Without that file the check will run, e.g. after a clean checkout or after running the clean task.
- always, this will check on any run of Gradle or a processor task if a newer version is available.

To configure a processor, for example openapi-processor-spring, place a spring configuration into the openapiProcessor block. The name of the configuration is used to create a Gradle task process<Name> to run the corresponding processor.

Kotlin
Groovy

// build.gradle.kts

openapiProcessor {

    // the path to the open api YAML file.
    apiPath("${projectDir}/src/api/openapi.yaml")
    // alternatives, since 2025.1
    // apiPath(file("$projectDir/src/api/openapi.yaml"))
    // apiPath(layout.projectDirectory.file("src/api/openapi.yaml"))

    process("spring") {
        // ... options of openapi-processor-spring
    }

}

// build.gradle

openapiProcessor {

    // the path to the open api YAML file.
    apiPath "${projectDir}/src/api/openapi.yaml"
    // alternatives, since 2025.1
    //apiPath file("$projectDir/src/api/openapi.yaml")
    //apiPath layout.projectDirectory.file("src/api/openapi.yaml")

    spring {
        // ... options of openapi-processor-spring
    }

}

In case another processor (e.g. JSON) is required place its configuration into the openapiProcessor block in the same way:

Kotlin
Groovy

// build.gradle.kts

openapiProcessor {

    // the path to the open api YAML file.
    apiPath("${projectDir}/src/api/openapi.yaml")
    // alternatives, since 2025.1
    // apiPath(file("$projectDir/src/api/openapi.yaml"))
    // apiPath(layout.projectDirectory.file("src/api/openapi.yaml"))

    process("spring") {
        // ... options of openapi-processor-spring
    }

    process("json") {
        // ... options of openapi-processor-json
    }

}

// build.gradle

openapiProcessor {

    // the path to the open api YAML file.
    apiPath "${projectDir}/src/api/openapi.yaml"
    // alternatives, since 2025.1
    // apiPath file("$projectDir/src/api/openapi.yaml")
    // apiPath layout.projectDirectory.file("src/api/openapi.yaml")

    spring {
        // ... options of openapi-processor-spring
    }

    json {
        // ... options of openapi-processor-json
    }

}

The configuration of a single processor has a few pre-defined properties, and it can have any number of additional parameters defined by the processor. All options will be passed in a map to the processor with the option name as the key.

processor (mandatory): the processor dependency. Uses the same dependency notations allowed in the gradle dependencies block.

The processor library is configured here to avoid any side effect on the build dependencies of the project.

Example using the preferred shortcut nation:

Kotlin
Groovy

process("spring") {
    processor("io.openapiprocessor:openapi-processor-spring:<version>")
}

spring {
    processor 'io.openapiprocessor:openapi-processor-spring:<version>'
}

or like this to use an un-published processor:

Kotlin
Groovy

process("spring") {
    processor(files("... path to processor jar"))
}

spring {
    processor files('... path to processor jar')
}

It is possible to use multiple processor entries to control the dependencies of an openapi-processor.

For example, the java generating processors depend on openapi-processor-core. The core library provides most of the logic of a processor, and it is usually enough to update the core library to get bugfixes or new features.

To find 'SNAPSHOT' versions the plugin automatically adds the snapshot repository to the repositories.

since 2022.2 In case you don’t want this it is possible to disable adding the snapshot repository by adding openapi-processor-gradle.snapshots = false to gradle.properties).

Kotlin
Groovy

process("spring") {
   processor("io.openapiprocessor:openapi-processor-core:2021.3-SNAPSHOT")
   processor("io.openapiprocessor:openapi-processor-spring:2021.1")
}

spring {
   processor 'io.openapiprocessor:openapi-processor-core:2021.3-SNAPSHOT'
   processor 'io.openapiprocessor:openapi-processor-spring:2021.1'
}

apiPath (optional): the path to the open api YAML file. If set inside a processor configuration it overrides the parent apiPath.
targetDir (mandatory): the target folder for the processor. The processor will write its output to this directory.
prop(key, value) or prop(Map<String, ?>) (optional): used to configure processor specific options. It just fills a map that is passed to the processor. It is not needed in a groovy dsl which automatically adds any unknown property to the processor options map.
- Kotlin
- Groovy
process("spring") { prop("mapping", "..path..") }
spring { mapping "..path.." }

gradle tasks

The plugin creates a single Gradle task for each processor configuration that will run the corresponding processor. By default, the name gets derived from the name of the processor: process<Name>.

The plugin does not add the process<Name> task to the build lifecycle.

To automatically run it

add a task dependency in the build.gradle file
or use the task output when configuring the additional SourceSet directories (see using the task output)

The second way is the newer and preferred way.

`dependOn` a processing task

This will continue to work but using the task output is the better and preferred configuration.

To automatically run a processing task, e.g. processSpring, it is necessary to create a dependency on the task.

Here is a simple example:

Kotlin
Groovy

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

// generate api before compiling
tasks.withType<KotlinCompile> {
    dependsOn("processSpring")
}

// generate api resource before processing
tasks.withType<ProcessResources> {
    dependsOn("processSpring")
}

// generate api before compiling
compileJava.dependsOn ('processSpring')

using the task name

The Gradle plugin creates the processing tasks inside an afterEvaluate block (because its name is configurable). To directly use its name, like in the example below, the configuration needs to be in an afterEvaluate block.

// groovy
tasks.register('prepareProcessing') {
    doLast {
        println 'preparing processing...'
    }
}

afterEvaluate {
    tasks.processSpring.dependsOn('prepareProcessing')
}

using the task output

In case the processor creates java sources it is necessary to compile them as part of the build process.

To compile the java source files created by openapi-processor-spring add the targetDir of the processor to the java sourceSets.

There are two ways to configure it:

using a path string which will need the dependsOn configuration to trigger the processor before compilation
or using the task output, which will avoid the need for dependsOn. Gradle will automatically detect that it has to run the processor first.

by path string

Using a path string it is simply added as an additional srcDir:

Kotlin
Groovy

// add the targetDir of the processor as additional source folder to java.
sourceSets {
    main {
        java {
            // add generated files
            srcDir("build/openapi")
            //srcDir(layout.buildDirectory.dir("openapi"))
        }
    }
}

// add the targetDir of the processor as additional source folder to java.
sourceSets {
    main {
        java {
            // add generated files
            srcDir 'build/openapi'
            //srcDir layout.buildDirectory.dir("openapi")
        }
    }
}

To add a JSON file created by the openapi-processor-json or another generated file to the final artifact jar as resource add, the targetDir of the processor to the java resources source set:

Kotlin
Groovy

// add the targetDir of the processor as additional resource folder.
sourceSets {
    main {
        resources {
            srcDir("$buildDir/json")
        }
    }
}

// add the targetDir of the processor as additional resource folder.
sourceSets {
    main {
        resources {
            srcDir "$buildDir/json"
        }
    }
}

by task output

since 2025.1

A preferred approach to avoid dependsOn and to support lazy configuration is to use the task output to configure the additional SourceSet directories.

Kotlin

import io.openapiprocessor.gradle.OpenApiProcessorTask

sourceSets {
    create("api") {
        resources {
            // add api resources
            srcDir("${projectDir}/src/api")
        }
    }

    afterEvaluate {
        // if the processor generates java files only, directly to targetDir
        main {
            java {
                // add generated files
                srcDir(tasks.named("processSpring"))
            }
        }

        // if the processor generates java and resource files to the targetDir it is necessary to select the subfolder
        main {
            java {
                // add generated files
                srcDir(tasks.named<OpenApiProcessorTask>("processSpring").map { it.getTargetDir().dir("java") })
            }
            resources {
                // add generated resources
                srcDir(tasks.named<OpenApiProcessorTask>("processSpring").map { it.getTargetDir().dir("resources") })
            }
        }
    }
}

processing multiple openapi files

By default, the name of a processor configuration block is used to select the processor library. Each processor library has a name and the plugin tries to load the processor library with that name.

This way it is not possible to process multiple distinct openapi descriptions with the same processor.

To achieve this it is possible to use user selected names for the processor blocks and explicitly configure the processor name using processorName():

Kotlin
Groovy

// build.gradle.kts

openapiProcessor {
    process("apiOne") { (1)
      processorName("spring") (2)

      apiPath("${projectDir}/src/api-one/openapi.yaml")
        // ... options of openapi-processor-spring
    }

    process("apiTwo") { (1)
      processorName("spring") (2)

      apiPath("${projectDir}/src/api-two/openapi.yaml")
        // ... options of openapi-processor-json
    }
}

// build.gradle

openapiProcessor {
    apiOne { (1)
      processorName "spring" (2)

      apiPath "${projectDir}/src/api-one/openapi.yaml"
        // ... options of openapi-processor-spring
    }

    apiTwo { (1)
      processorName "spring" (2)

      apiPath "${projectDir}/src/api-two/openapi.yaml"
        // ... options of openapi-processor-spring
    }
}

1	user selected name for the configuration. It is used to create the task name (in this case `processApiOne` & `processApiTwo`).
2	explicit name of the processor to use.

The plugin configures the parent directory of the openapi file (i.e. apiPath) and the targetDir for the up-to-date check of each processXX gradle task. If the inputs and outputs are unchanged Gradle will not re-run the task.

To keep this working and to avoid unnecessary re-runs of the processor tasks it is recommended to use distinct folders for each api file.

using plugin snapshots

Sometimes it is useful to try a special plugin version instead of the published plugin from the plugin portal. For example to try a snapshot or test version of the plugin.

This is possible by configuring the repositories checked for plugins using a pluginManagement block in settings.gradle (this must be at the top of the file). The example below adds the snapshot repository of the Gradle plugin.

// build.gradle

plugins {
    id 'io.openapiprocessor.openapi-processor" version "2025.6-SNAPSHOT'
}


// settings.gradle

pluginManagement {
    repositories {
        maven {
            url 'https://central.sonatype.com/repository/maven-snapshots'
        }
        gradlePluginPortal()
    }
}

// ...

configuration example

Here is a full example that configures openapi-processor-spring and openapi-processor-json:

Kotlin
Groovy

// build.gradle.kts

openapiProcessor {

    // the path to the open api YAML file. Usually the same for all processors.
    //
    //apiPath("${projectDir}/src/api/openapi.yaml")
    apiPath(layout.projectDirectory.file("src/api/openapi.yaml"))

    // based on the name of a processor configuration the plugin creates a Gradle task with name
    // "process${name of processor}"  (in this case "processSpring") to run the processor.
    //
    process("spring") {
        // the openapi-processor-spring dependency (mandatory)
        //
        processor("io.openapiprocessor:openapi-processor-spring:<version>")

        // setting api path inside a processor configuration overrides the one at the top.
        //
        // apiPath("${projectDir}/src/api/openapi.yaml")

        // the destination folder for generating interfaces & models. This is the parent of the
        // {package-name} folder tree configured in the mapping file. (mandatory)
        //
        //targetDir("${projectDir}/build/openapi")
        targetDir(layout.buildDirectory.dir("openapi"))

        //// openapi-processor-spring specific options
        //// in a kotlin build script it is necessary to use the prop(key, value) or prop(map)
        //// method to set processor specific options.

        // file name of the mapping YAML configuration file. Note that the YAML file name must end
        // with either {@code .yaml} or {@code .yml}.
        //
        //prop("mapping", "${projectDir}/src/api/mapping.yaml")
        prop("mapping", layout.projectDirectory.file("src/api/mapping.yaml"))
    }

    // applying the rule described above the task to run this one is "processJson".
    //
    process("json") {
        // the openapi-processor-json dependency (mandatory)
        //
        processor("'io.openapiprocessor:openapi-processor-json:<version>")

        // the destination folder for the JSON file. (mandatory)
        //targetDir("${buildDir}/json")
        targetDir(layout.buildDirectory.dir("json"))
    }
}

// build.gradle

openapiProcessor {

    // the path to the open api yaml file. Usually the same for all processors.
    //
    // apiPath "${projectDir}/src/api/openapi.yaml"
    apiPath layout.projectDirectory.file("src/api/openapi.yaml")

    // based on the name of a processor configuration the plugin creates a gradle task with name
    // "process${name of processor}"  (in this case "processSpring") to run the processor.
    //
    spring {
        // the openapi-processor-spring dependency (mandatory)
        //
        processor 'io.openapiprocessor:openapi-processor-spring:<version>'

        // setting api path inside a processor configuration overrides the one at the top.
        //
        // apiPath "${projectDir}/src/api/openapi.yaml"

        // the destination folder for generating interfaces & models. This is the parent of the
        // {package-name} folder tree configured in the mapping file. (mandatory)
        //
        //targetDir "${projectDir}/build/openapi"
        targetDir layout.buildDirectory.dir("openapi")

        //// openapi-processor-spring specific options

        // file name of the mapping yaml configuration file. Note that the yaml file name must end
        // with either {@code .yaml} or {@code .yml}.
        //
        //mapping "${projectDir}/src/api/mapping.yaml"
        mapping layout.projectDirectory.file("src/api/mapping.yaml")
    }

    // applying the rule described above the task to run this one is "processJson".
    //
    json {
        // the openapi-processor-json dependency (mandatory)
        //
        processor 'io.openapiprocessor:openapi-processor-json:<version>'

        // the destination folder for the json file. (mandatory)
        //targetDir "${buildDir}/json"
        targetDir layout.buildDirectory.dir("json")
    }

}

without the comments it is not that long:

Kotlin
Groovy

// build.gradle.kts

openapiProcessor {
    apiPath(layout.projectDirectory.file("src/api/openapi.yaml"))

    process("spring") {
        processor("io.openapiprocessor:openapi-processor-spring:<version>")
        targetDir(layout.buildDirectory.dir("openapi"))
        prop("mapping", layout.projectDirectory.file("src/api/mapping.yaml"))
    }

    process("json") {
        processor("io.openapiprocessor:openapi-processor-json:<version>")
        targetDir(layout.buildDirectory.dir("json"))
    }
}

// build.gradle

openapiProcessor {
    apiPath layout.projectDirectory.file("src/api/openapi.yaml")

    spring {
        processor "io.openapiprocessor:openapi-processor-spring:<version>"
        targetDir layout.buildDirectory.dir("openapi")
        mapping layout.projectDirectory.file("src/api/mapping.yaml")
    }

    json {
        processor "io.openapiprocessor:openapi-processor-json:<version>"
        targetDir layout.buildDirectory.dir("json")
    }
}

samples

See samples for working samples using the groovy and kotlin dsl.