Gradle Swagger Generator Plugin

This is a Gradle plugin to do following tasks:

Validate an OpenAPI YAML.
Generate source from an OpenAPI YAML using Swagger Codegen.
Generate Swagger UI with an OpenAPI YAML.
Generate ReDoc with an OpenAPI YAML.

Code Generation

Create a project with following build script.

plugins {
  id 'org.hidetake.swagger.generator' version '2.12.0'
}

repositories {
  jcenter()
}

dependencies {
  // Add dependency for Swagger Codegen CLI
  swaggerCodegen 'io.swagger:swagger-codegen-cli:2.3.1'
}

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      configFile = file('config.json')
    }
  }
}

The task generates source code into build/swagger-code-petstore.

% ./gradlew generateSwaggerCode
:resolveSwaggerTemplate NO-SOURCE
:generateSwaggerCodePetstore
:generateSwaggerCode NO-SOURCE

Run the task with Help postfix to show available rawOptions and JSON configuration.

% ./gradlew generateSwaggerCodePetstoreHelp
:generateSwaggerCodePetstoreHelp
=== Available raw options
NAME
        swagger-codegen-cli generate - Generate code with chosen lang

SYNOPSIS
        swagger-codegen-cli generate
                [(-a <authorization> | --auth <authorization>)]
...

=== Available JSON configuration for language spring:

CONFIG OPTIONS
	sortParamsByRequiredFlag
...

Document Generation

Swagger UI

Create a project with following build script.

plugins {
  id 'org.hidetake.swagger.generator' version '2.12.0'
}

dependencies {
  // Add dependency for Swagger UI
  swaggerUI 'org.webjars:swagger-ui:3.10.0'
}

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
  }
}

The task generates an API document as build/swagger-ui-petstore.

% ./gradlew generateSwaggerUI
:generateSwaggerUIPetstore
:generateSwaggerUI NO-SOURCE

If you need Swagger UI 2.x, see doc-generator-swagger-ui-v2 project in examples.

ReDoc

Create a project with following build script.

plugins {
  id 'org.hidetake.swagger.generator' version '2.12.0'
}

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
  }
}

The task generates an API document as build/redoc-petstore.

% ./gradlew generateSwaggerReDoc
:generateReDocPetstore
:generateReDoc NO-SOURCE

Recipes

There are some examples in acceptance-test project.

Build generated code

It is recommended to generate code into build directory and exclude from a Git repository. We can compile generated code as follows:

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      configFile = file('config.json')
    }
  }
}

// Configure compile task dependency and source
compileJava.dependsOn swaggerSources.petstore.code
sourceSets.main.java.srcDir "${swaggerSources.petstore.code.outputDir}/src/main/java"
sourceSets.main.resources.srcDir "${swaggerSources.petstore.code.outputDir}/src/main/resources"

For more, see code-generator project in examples.

Validate YAML before code genetation

It is recommended to validate an OpenAPI YAML before code generation in order to avoid invalid code generated. We can validate a YAML as follows:

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      configFile = file('config.json')
      // Validate YAML before code generation
      dependsOn validation
    }
  }
}

For more, see code-generator project in examples.

Selective generation

We can control output of code generation. At default everything is generated but only models and APIs are generated in following:

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      configFile = file('config.json')
      // Generate only models and controllers
      components = ['models', 'apis']
    }
  }
}

components property accepts a list of strings or map.

// generates only models
components = ['models']
components = [models: true]

// generate only User and Pet models
components = [models: ['User', 'Pet']]
components = [models: 'User,Pet']

// generate only APIs (without tests)
components = [apis: true, apiTests: false]
components = [apis: true, apiTests: null]

For details, see selective generation.

Using custom template

We can use a custom template for the code generation as follows:

// build.gradle
swaggerSources {
  inputFile = file('petstore.yaml')
  petstore {
    language = 'spring'
    // Path to the template directory
    templateDir = file('templates/spring-mvc')
  }
}

For more, see custom-template project in examples.

Using custom generator class

We can use a custom generator class for the code generation as follows:

// build.gradle
swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      // FQCN of the custom generator class
      language = 'CustomGenerator'
    }
  }
}

// buildSrc/build.gradle
repositories {
  jcenter()
}

dependencies {
  // Add dependency here (do not specify in the parent project)
  compile 'io.swagger:swagger-codegen-cli:2.3.1'
}

// buildSrc/src/main/groovy/CustomGenerator.groovy
import io.swagger.codegen.languages.SpringCodegen

class CustomGenerator extends SpringCodegen {
}

For more, see custom-class project in examples.

Externalize template or generator class

In some large use case, we can release a template or generator to an external repository and use them from projects.

// build.gradle
repositories {
  // Use external repository for the template and the generator class
  maven {
    url 'https://example.com/nexus-or-artifactory'
  }
  jcenter()
}

dependencies {
  swaggerCodegen 'io.swagger:swagger-codegen-cli:2.3.1'
  // Add dependency for the template
  swaggerTemplate 'com.example:swagger-templates:1.0.0'
  // Add dependency for the generator class
  swaggerCodegen 'com.example:swagger-generators:1.0.0'
}

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      // The plugin automatically extracts template JAR into below destination
      templateDir = file("${resolveSwaggerTemplate.destinationDir}/spring-mvc")
    }
  }
}

For more, see externalize-template project and externalize-class project in examples.

Multiple sources

We can handle multiple sources in a project as follows:

// build.gradle
swaggerSources {
    petstoreV1 {
        inputFile = file('v1-petstore.yaml')
        code {
            language = 'spring'
            configFile = file('v1-config.json')
        }
    }
    petstoreV2 {
        inputFile = file('v2-petstore.yaml')
        code {
            language = 'spring'
            configFile = file('v2-config.json')
        }
    }
}

compileJava.dependsOn swaggerSources.petstoreV1.code, swaggerSources.petstoreV2.code
sourceSets.main.java.srcDirs "${swaggerSources.petstoreV1.code.outputDir}/src/main/java", "${swaggerSources.petstoreV2.code.outputDir}/src/main/java"
sourceSets.main.resources.srcDirs "${swaggerSources.petstoreV1.code.outputDir}/src/main/resources", "${swaggerSources.petstoreV2.code.outputDir}/src/main/resources"

For more, see multiple-sources project in examples.

Configure Swagger UI

We can configure Swagger UI by overwriting the default index.html as follows:

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    ui {
      doLast {
        copy {
          from 'index.html'
          into outputDir
        }
      }
    }
  }
}

You can create an index.html from the Swagger UI official one. It must satisfy the followings:

Put <script src="./swagger-spec.js"> in order to load a Swagger spec. The plugin exports the Swagger spec as swagger-spec.js file while generation.
Set spec: window.swaggerSpec in SwaggerUIBundle() parameters.
Set validatorUrl: null in SwaggerUIBundle() parameters in order to turn off the validator badge.

If you need Swagger UI 2.x, see doc-generator-swagger-ui-v2 project in examples.

Settings

The plugin adds validateSwagger, generateSwaggerCode, generateSwaggerUI and GenerateReDoc tasks. A task will be skipped if no input file is given.

Task type `ValidateSwagger`

The task accepts below properties.

Key	Type	Value	Default value
`inputFile`	File	Swagger spec file.	Mandatory
`reportFile`	File	File to write validation report.	`$buildDir/tmp/validateSwagger/report.yaml`

Task type `GenerateSwaggerCode`

The task accepts below properties.

Key	Type	Value	Default value
`language`	String	Language to generate.	Mandatory
`inputFile`	File	Swagger spec file.	Mandatory
`outputDir`	File	Directory to write generated files.	`$buildDir/swagger-code`
`wipeOutputDir`	Boolean	Wipe the `outputDir` before generation.	`true`
`library`	String	Library type.	None
`configFile`	File	JSON configuration file.	None
`templateDir`	File	Directory containing the template.	None
`components`	List or Map	Components to generate that is a list of `models`, `apis` and `supportingFiles`.	All components
`additionalProperties`	Map of String, String	Additional properties.	None
`rawOptions`	List of Strings	Raw command line options for Swagger Codegen	None

Task type `GenerateSwaggerUI`

The task accepts below properties.

Key	Type	Value	Default value
`inputFile`	File	Swagger spec file.	Mandatory
`outputDir`	File	Directory to write Swagger UI files.	`$buildDir/swagger-ui`
`wipeOutputDir`	Boolean	Wipe the `outputDir` before generation.	`true`

Note that options and header are no longer supported since 2.10.0. See the Migration Guide for details.

Task type `GenerateReDoc`

The task accepts below properties.

Key	Type	Value	Default value
`inputFile`	File	Swagger spec file.	Mandatory
`outputDir`	File	Directory to write ReDoc files.	`$buildDir/swagger-redoc`
`wipeOutputDir`	Boolean	Wipe the `outputDir` before generation.	`true`
`scriptSrc`	String	URL to ReDoc JavaScript.	`//rebilly.github.io/ReDoc/releases/latest/redoc.min.js`
`options`	Map of Strings	ReDoc tag attributes.	Empty map

Contributions

This is an open source software licensed under the Apache License Version 2.0. Feel free to open issues or pull requests.

CircleCI builds the plugin continuously. Following variables should be set.

Environment Variable	Purpose
`$GRADLE_PUBLISH_KEY`	Publish the plugin to Gradle Plugins
`$GRADLE_PUBLISH_SECRET`	Publish the plugin to Gradle Plugins

dstepanov / gradle-swagger-generator-plugin

Gradle Swagger Generator Plugin

Code Generation

Document Generation

Swagger UI

ReDoc

Recipes

Build generated code

Validate YAML before code genetation

Selective generation

Using custom template

Using custom generator class

Externalize template or generator class

Multiple sources

Configure Swagger UI

Settings

Task type `ValidateSwagger`

Task type `GenerateSwaggerCode`

Task type `GenerateSwaggerUI`

Task type `GenerateReDoc`

Contributions

About

Languages

Gradle Swagger Generator Plugin

Code Generation

Document Generation

Swagger UI

ReDoc

Recipes

Build generated code

Validate YAML before code genetation

Selective generation

Using custom template

Using custom generator class

Externalize template or generator class

Multiple sources

Configure Swagger UI

Settings

Task type ValidateSwagger

Task type GenerateSwaggerCode

Task type GenerateSwaggerUI

Task type GenerateReDoc

Contributions

About

Languages

Task type `ValidateSwagger`

Task type `GenerateSwaggerCode`

Task type `GenerateSwaggerUI`

Task type `GenerateReDoc`