Gradle Plugin

The openapi-processor-gradle is currently the only tool to run any of the openapi-processor's.

To use it in a gradle project the gradle file of the project requires a few additional instructions. The following sections describe how to activate & configure openapi-processor-spring in a build.gradle file.

adding the plugin

To activate the plugin add it to (like any other gradle plugin) the plugins configuration:

plugins {
    // add openapi-processor-gradle plugin
    id 'io.openapiprocessor.openapi-processor' version '<version>'

configuring processor-spring

The plugin will add an openapiProcessor configuration block that is used to configure the processors. Configuration for a specific processor belongs inside it with the processor name as configuration block name.

openapiProcessor {

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

  • processor: (required) the processor dependency. This works in the same way as adding a dependency to a configuration in the gradle dependencies block. It is given here to avoid un-wanted side effects on the build dependencies of the project.

  • apiPath: (required) the path to the openapi.yaml file and the main input for the processor. If set in the top-level block it will be used for all configured processors.

  • targetDir: (required) the output folder for generating interfaces & models. This is the parent of the packageName folder tree. It is recommended to set this to a subfolder of gradle’s standard build directory, so it is cleared by the clean task and does not pollute the sources directory.

    See running processor-spring how to include the targetDir in compilation & packing.

  • mapping: (required) provides the processor mapping options. This is a path to yaml file. See Configuration for a description of the mapping yaml. This replaces the typeMappings option.

  • showWarnings: (optional) true to show warnings from the open api parser or false (default) to show no warnings (this option has currently no effect).

  • parser: (optional), sets the openapi parser used to read the OpenAPI description. Available values are SWAGGER (default), OPENAPI4J or INTERNAL.

    • SWAGGER: Swagger OpenAPI parser, supports OpenAPI 3.0.x

    • OPENAPI4J: openapi4j OpenAPI parser, supports OpenAPI 3.0.x. It provides better validation than SWAGGER, unfortunately it is no longer maintained.

    • INTERNAL: internal OpenAPI parser, supports OpenAPI 3.0.x & OpenAPI 3.1.0.

      • the 3.0.x parser provides JSON schema validation.

      • the 3.1.0 parser is experimental and has no validation at the moment.

running processor-spring

The plugin will add a gradle task processSpring to run the processor.

To automatically generate & compile the processor output two additional configurations are necessary.

  • the sourceSets are extended to include the processor output (assuming a java project):

    sourceSets {
        main {
            java {
                // add generated files
                srcDir 'build/openapi'
  • and the compileJava task gets a dependency on processSpring, so it runs before compilation (again, assuming a java project):

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

Adding automatic compilation in this way will also automatically include the generated files into the jar build artifact.