swagger-gradle-plugin

swagger-gradle-plugin supports gradle 3.2 and higher.

Jakarta namespace support

Since version 2.1.7 Swagger Core supports also Jakarta namespace, with a parallel set of artifacts with -jakarta suffix, providing the same functionality as the "standard" javax namespace ones. Please check Wiki for more details

To have gradle plugin use the jakarta namespace artifacts, you need to provide a value to parameter buildClasspath In many cases it is sufficient to set it to the classpath value, like:

buildClasspath = classpath

Alternatively provide as value a classpath with the following dependencies (replacing the provided javax ones):

org.apache.commons:commons-lang3:3.20.0
io.swagger.core.v3:swagger-jaxrs2-jakarta:2.2.9
jakarta.ws.rs:jakarta.ws.rs-api:3.0.0
jakarta.servlet:jakarta.servlet-api:5.0.0

Installation

Gradle 3.2 and higher

plugins {
  id "io.swagger.core.v3.swagger-gradle-plugin" version "2.2.49"
}

Gradle 1.x and 2.0

NOTE: Since version 2.0.10 gradle 1.x and 2.x up to 3.1 are not supported.

with versions up to 2.0.9:

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "io.swagger.core.v3:swagger-gradle-plugin:2.2.49"
  }
}

apply plugin: "io.swagger.core.v3.swagger-gradle-plugin"

Tasks

resolve

Resolves project openAPI specification and saves the result in JSON, YAML or both formats. All parameters except outputFileName, outputFormat, classpath, skip, encoding, outputDir and outputPath correspond to swagger configuration property with same name.

Example Usage


resolve {
    outputFileName = 'PetStoreAPI'
    outputFormat = 'JSON'
    prettyPrint = 'TRUE'
    classpath = sourceSets.main.runtimeClasspath
    resourcePackages = ['io.test']
    outputDir = file('test')
}

Parameters

Parameter	Description	Required	Default
`classpath`	classpath for resources to scan (swagger and deps already included in classpath)	true
`outputDir`	output path where file(s) are saved	true
`outputFileName`	file name (no extension)	false	`openapi`
`outputFormat`	file format (`JSON`, `YAML`, `JSONANDYAML`	false	`JSON`
`skip`	if `TRUE` skip execution	false	`FALSE`
`encoding`	encoding of output file(s)	false
`resourcePackages`	see configuration property	false
`resourceClasses`	see configuration property	false
`prettyPrint`	see configuration property	false	`TRUE`
`sortOutput`	see configuration property	false	`FALSE`
`alwaysResolveAppPath`	see configuration property	false	`FALSE`
`skipResolveAppPath`	see configuration property	false	`FALSE`
`openApiFile`	openapi file to be merged with resolved specification, equivalent to config openAPI	false
`filterClass`	see configuration property	false
`readerClass`	see configuration property	false
`scannerClass`	see configuration property	false
`readAllResources`	see configuration property	false
`ignoredRoutes`	see configuration property	false
`objectMapperProcessorClass`	see configuration property	false
`modelConverterClasses`	see configuration property	false
`contextId`	see Context	false
`outputPath`	DEPRECATED output path where file(s) are saved	false
`defaultResponseCode`	see configuration property	false
`groupsValidationStrategy`	see configuration property	false
`validatorProcessorClass`	see configuration property	false
`openapi31`	see configuration property	false
`schemaResolution`	see configuration property	DEFAULT
`openAPIVersion`	see configuration property	`3.0.1/3.1.0`

Note parameter openApiFile corresponds to config openAPI. It points to a location of a file in YAML or JSON format representing the input spec that will be merged with the resolved spec. Typically used to add Info section, or any other meta data. An example of such file:

yaml

openapi: 3.0.4
info:
  version: '1.0'
  title: Swagger Pet Sample App Config File
  description: 'This is a sample server Petstore server.  You can find out more
    about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net,
    #swagger](http://swagger.io/irc/).  For this sample, you can use the api key
    special-key to test the authorization filters.'
  termsOfService: http://swagger.io/terms/
  contact:
    email: [email protected]
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

Since version 2.1.6, sortOutput parameter is available, allowing to sort object properties and map keys alphabetically.
Since version 2.1.6, objectMapperProcessorClass allows to configure also the ObjectMapper instance used to serialize the resolved OpenAPI
Since version 2.1.9, alwaysResolveAppPath parameter is available, allowing to trigger resolving of Application Path from annotation also not in runtime (e.g. using servlet in separate application, or in maven plugin at build time, etc)
Since version 2.2.12, openapi31 parameter is available, if set to true the resolved spec will be processed into a 3.1.0 specification by resolving according to OAS 3.1 rules
Since version 2.1.15, skipResolveAppPath parameter is available, allowing to skip resolving of Application Path from annotation
Since version 2.2.17, defaultResponseCode parameter is available, allowing to set the code used when resolving responses with no http status code annotation
Since version 2.2.24, schemaResolution parameter is available, allowing to specify how object schemas and object properties within schemas are resolved for OAS 3.0 specification
Since version 2.2.28, openAPIVersion parameter is available, allowing to specify the version of the OpenAPI specification to be used for the resolved spec.
Since version 2.2.29, groupsValidationStrategy parameter is available, allowing to specify the strategy for resolving Validation annotations (never, always, neverIfNoContext).
Since version 2.2.29, validatorProcessorClass parameter is available, allowing to specify a custom validator processor class, implementation of io.swagger.v3.core.util.ValidatorProcessor.