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	required gradle version
2022.1 or newer	7.0+
2021.3	5.5+ with groovy dsl, 6.5 with kotlin dsl

plugin version

required gradle version

2022.1 or newer

7.0+

2021.3

5.5+ with groovy dsl, 6.5 with kotlin dsl

unfortunately it is necessary to configure a few additional jvm parameter to run 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.

Groovy
Kotlin

// build.gradle

openapiProcessor {

    // the path to the open api yaml file.
    apiPath "${projectDir}/src/api/openapi.yaml"

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

}

// build.gradle.kts

openapiProcessor {

    // the path to the open api yaml file.
    apiPath("${projectDir}/src/api/openapi.yaml")

    process("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:

Groovy
Kotlin

// build.gradle

openapiProcessor {

    // the path to the open api yaml file.
    apiPath "${projectDir}/src/api/openapi.yaml"

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

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

}

// build.gradle.kts

openapiProcessor {

    // the path to the open api yaml file.
    apiPath("${projectDir}/src/api/openapi.yaml")

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

    process("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:
- Groovy
- Kotlin
spring { processor 'io.openapiprocessor:openapi-processor-spring:<version>' }
process("spring") { processor("io.openapiprocessor:openapi-processor-spring:<version>") }
or like this to use an un-published processor:
- Groovy
- Kotlin
spring { processor files('... path to processor jar') }
process("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).
- Groovy
- Kotlin
spring { processor 'io.openapiprocessor:openapi-processor-core:2021.3-SNAPSHOT' processor 'io.openapiprocessor:openapi-processor-spring:2021.1' }
process("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.
- Groovy
- Kotlin
spring { mapping "..path.." }
process("spring") { prop("mapping", "..path..") }

gradle tasks

The plugin creates a single gradle task for each processor configuration that will run the corresponding processor. 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. For example to run openapi-processor-spring before compiling use:

Groovy
Kotlin

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

tasks.compileJava {
  dependsOn("processSpring")
}

to run openapi-processor-json when processing the resources:

Groovy
Kotlin

processResources.dependsOn ('processJson')

tasks.processResources {
    dependsOn("processJson")
}

`dependOn` a processing task

If a task needs to run before a processing task, e.g. processSpring, it is necessary to create the dependency inside an afterEvaluate block.

The gradle plugin creates the processing tasks inside an afterEvaluate block and therefore they are not visible outside afterEvaluate.

Here is a simple example:

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

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

using the processor output

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

For example to compile the java source files created by openapi-processor-spring add the targetDir`of the processor to the java `sourceSets:

Groovy
Kotlin

// add the targetDir of the processor as additional source folder to java.
sourceSets {
    main {
        java {
            // add generated files
            srcDir 'build/openapi'
        }
    }
}

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

To add the json file created by the openapi-processor-json to the final artifact jar as resource add the targetDir of the processor to the java resources source set:

Groovy
Kotlin

// 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")
        }
    }
}

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():

Groovy
Kotlin

// 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
    }
}

// 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
    }
}

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 "2022.2-SNAPSHOT'
}


// settings.gradle

pluginManagement {
    repositories {
        maven {
            url 'https://oss.sonatype.org/content/repositories/snapshots'
        }
        gradlePluginPortal()
    }
}

// ...

configuration example

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

Groovy
Kotlin

// build.gradle

openapiProcessor {

    // the path to the open api yaml file. Usually the same for all processors.
    //
    apiPath "${projectDir}/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"

        //// 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"
    }

    // 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"
    }

}

// build.gradle.kts

openapiProcessor {

    // the path to the open api yaml file. Usually the same for all processors.
    //
    apiPath("${projectDir}/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")

        //// 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")
    }

    // 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")
    }

}

without the comments it is not that long:

Groovy
Kotlin

// build.gradle

openapiProcessor {
    apiPath "${projectDir}/src/api/openapi.yaml"

    spring {
        processor 'io.openapiprocessor:openapi-processor-spring:<version>'
        targetDir "${projectDir}/build/openapi"
        mapping "${projectDir}/src/api/mapping.yaml"
    }

    json {
        processor 'io.openapiprocessor:openapi-processor-json:<version>'
        targetDir "${buildDir}/json"
    }
}

// build.gradle.kts

openapiProcessor {
    apiPath("${projectDir}/src/api/openapi.yaml")

    process("spring") {
        processor("io.openapiprocessor:openapi-processor-spring:<version>")
        targetDir("${projectDir}/build/openapi")
        prop("mapping", "${projectDir}/src/api/mapping.yaml")
    }

    process("json") {
        processor("io.openapiprocessor:openapi-processor-json:<version>")
        targetDir("${buildDir}/json")
    }
}

samples

See spring mvc sample or spring webflux sample for working spring boot samples using the groovy dsl.