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.