Skip to main content

# Plugins

## Maven​

A Maven plugin to support the OpenAPI generator project

### Example​

Add to your `build->plugins` section (default phase is `generate-sources` phase)

    <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <!-- RELEASE_VERSION -->
        <version>6.6.0</version>
        <!-- /RELEASE_VERSION -->
        <executions>
            <execution>
                <goals>
                    <goal>generate</goal>
                </goals>
                <configuration>
                    <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
                    <generatorName>java</generatorName>
                    <configOptions>
                       <sourceFolder>src/gen/java/main</sourceFolder>
                    </configOptions>
                </configuration>
            </execution>
        </executions>
    </plugin>

Followed by:

    mvn clean compile

For full details of all options, see the plugin README.

### Dependencies​

The generated models use commonly used Swagger v2 annotations like `@ApiModelProperty`. A user may add Swagger v3 annotations:

    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-annotations</artifactId>
    </dependency>

But this will not work. This dependency is not binary compatible with Swagger v2 annotations. The resulting code will fail to compile.

As alternative instead use the following dependency:

    <dependency>
        <groupId>io.swagger.parser.v3</groupId>
        <artifactId>swagger-parser</artifactId>
    </dependency>

## Gradle​

This gradle plugin offers a declarative DSL via extensions (these are Gradle project extensions). These map almost fully 1:1 with the options you’d pass to the CLI or Maven plugin. The plugin maps the extensions to a task of the same name to provide a clean API. If you’re interested in the extension/task mapping concept from a high-level, you can check out Gradle’s docs.

To include in your project, add the following to `build.gradle`:

    buildscript {
      repositories {
        mavenLocal()
        mavenCentral()
      }
      dependencies {
        classpath "org.openapitools:openapi-generator-gradle-plugin:6.6.0"
      }
    }

    apply plugin: 'org.openapi.generator'

This gives access to the following tasks:

Task | Description
--- | ---
openApiGenerate | Generate code via Open API Tools Generator for Open API 2.0 or 3.x specification documents.
openApiGenerators | Lists generators available via Open API Generators.
openApiMeta | Generates a new generator to be consumed via Open API Generator.
openApiValidate | Validates an Open API 2.0 or 3.x specification document.

> The plugin implements the above tasks as project extensions of the same name. If you’d like to declare these tasks as dependencies to other tasks (using `dependsOn`), you’ll need a task reference. e.g.:

>     compileJava.dependsOn tasks.named("openApiGenerate")

For full details of all options, see the plugin README.

### Example​

An example openApiGenerate task configuration for generating a kotlin client:

    openApiGenerate {
        generatorName.set("kotlin")
        inputSpec.set("$rootDir/specs/petstore-v3.0.yaml")
        outputDir.set("$buildDir/generated")
        apiPackage.set("org.openapi.example.api")
        invokerPackage.set("org.openapi.example.invoker")
        modelPackage.set("org.openapi.example.model")
        configOptions.set([
            dateLibrary: "java8"
        ])
    }

If you want to create separate tasks (for example when you have more than one api spec and require different parameters for each), this is how to do so in Gradle 7+: `tasks.register('taskName', org.openapitools.generator.gradle.plugin.tasks.GenerateTask) { ... }`.