openapi-processor-gradle

badge License Apache%202.0 blue

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

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 is only a single option that is 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.

To configure a processor, for example openapi-processor-spring, place a spring configuration into the openapiProcessor block. The name of the configuration gets 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"))
    }

    since 2021.2

    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.

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

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.

compatibility

plugin version plugin id minimum gradle version description

2021.3, (April 2021)

io.openapiprocessor.openapi-processor

5.5 (June 2019) groovy dsl
6.5 (June 2020) kotlin dsl

only supports processors with new io.openapiprocessor group id

2021.2, (March 2021)

io.openapiprocessor.openapi-processor

5.5 (June 2019)

only supports processors with new io.openapiprocessor group id

2021.1 (1.0.0.M10), (February 2021)

io.openapiprocessor.openapi-processor

5.5 (June 2019)

same as above

↓ old (deprecated)

1.0.0.M9

same as above

same as above

only supports processors with new io.openapiprocessor group id

1.0.0.M8

com.github.hauner.openapi-processor

5.2 (February 2019)

supports processors with new io.openapiprocessor and old com.github.hauner.openapi group id

1.0.0.M7

com.github.hauner.openapi-processor

5.2 (February 2019)

only supports processors com.github.hauner.openapi group id