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.

compatibility

plugin version plugin id minimum gradle version description

1.0.0.M9

io.openapiprocessor.openapi-processor

5.5 (June 2019)

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

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 the 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.

openapiProcessor {

    // the path to the open api yaml file.
    apiPath "${projectDir}/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:

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
    }

}

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:

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

    or like this to use an un-published processor:

    spring {
        processor files('... path to generatr jar')
    }
  • 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.

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: generate<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:

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

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

processResources.dependsOn ('processJson')

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:

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

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

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"

        // show warnings from the open api parser.
        showWarnings true
    }

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

}

without the comments it is not that long:

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"
        showWarnings true
    }

    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.