在线时间:8:00-16:00
迪恩网络APP
随时随地掌握行业动态
扫描二维码
关注迪恩网络微信公众号
开源软件名称(OpenSource Name):int128/gradle-swagger-generator-plugin开源软件地址(OpenSource Url):https://github.com/int128/gradle-swagger-generator-plugin开源编程语言(OpenSource Language):Groovy 92.1%开源软件介绍(OpenSource Introduction):Gradle Swagger Generator PluginTable of contentIntroductionThis is a Gradle plugin for the following tasks:
See also the following examples:
Code GenerationCreate a project with the following build script. plugins {
id 'org.hidetake.swagger.generator' version '2.19.2'
}
repositories {
mavenCentral()
}
dependencies {
swaggerCodegen 'io.swagger:swagger-codegen-cli:2.4.27' // Swagger Codegen V2
swaggerCodegen 'io.swagger.codegen.v3:swagger-codegen-cli:3.0.34' // or Swagger Codegen V3
swaggerCodegen 'org.openapitools:openapi-generator-cli:3.3.4' // or OpenAPI Generator
}
swaggerSources {
petstore {
inputFile = file('petstore.yaml')
code {
language = 'spring'
}
}
} The task generates source code into
Document GenerationSwagger UICreate a project with the following build script. plugins {
id 'org.hidetake.swagger.generator' version '2.19.2'
}
repositories {
mavenCentral()
}
dependencies {
swaggerUI 'org.webjars:swagger-ui:3.52.5'
}
swaggerSources {
petstore {
inputFile = file('petstore.yaml')
}
} The task generates an API document as
ReDocCreate a project with the following build script. plugins {
id 'org.hidetake.swagger.generator' version '2.19.2'
}
swaggerSources {
petstore {
inputFile = file('petstore.yaml')
}
} The task generates an API document as
HTMLCreate a project with the following build script. plugins {
id 'org.hidetake.swagger.generator' version '2.19.2'
}
repositories {
mavenCentral()
}
dependencies {
swaggerCodegen 'io.swagger:swagger-codegen-cli:2.4.27' // Swagger Codegen V2
swaggerCodegen 'io.swagger.codegen.v3:swagger-codegen-cli:3.0.34' // or Swagger Codegen V3
}
swaggerSources {
petstore {
inputFile = file('petstore.yaml')
code {
language = 'html' // html or html2
}
}
} The task generates a static HTML into
RecipesSee the example projects in acceptance-test. Use configuration fileWe can use a JSON configuration file as follows: swaggerSources {
petstore {
inputFile = file('petstore.yaml')
code {
language = 'spring'
configFile = file('config.json')
}
}
}
{
"library": "spring-mvc",
"modelPackage": "example.model",
"apiPackage": "example.api",
"invokerPackage": "example"
} Run the task with
Build generated codeIt is recommended to generate code into an ephemeral directory (e.g. 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" See also the following examples: Validate YAML before code generationIt is recommended to validate an OpenAPI YAML before code generation in order to avoid invalid code generated. If you use OpenAPI Generator as generator, YAML validation is embeding. 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. for Swagger Codegen V2 / V3
dependsOn validation
}
}
} Selective generationWe can control output of code generation. At default everything is generated but only models and APIs are generated in the following: swaggerSources {
petstore {
inputFile = file('petstore.yaml')
code {
language = 'spring'
configFile = file('config.json')
// Generate only models and controllers
components = ['models', 'apis']
}
}
}
// 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] See selective generation section for details. Use custom templateWe 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')
}
} See also the following examples: Use custom generator classWe 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'
}
}
}
dependencies {
swaggerCodegen project('generators')
}
swaggerSources*.code*.dependsOn 'generators:jar' // generators/build.gradle (child project)
dependencies {
implementation 'io.swagger:swagger-codegen-cli:2.4.24'
} // generators/src/main/groovy/CustomGenerator.groovy
import io.swagger.codegen.languages.SpringCodegen
class CustomGenerator extends SpringCodegen {
} See also the following examples: Externalize template or generator classIn 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'
}
mavenCentral()
}
dependencies {
swaggerCodegen 'io.swagger:swagger-codegen-cli:2.4.27'
// 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")
}
}
} See also the following examples:
Use multiple sourcesWe 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" See also the following examples: Switch version of Swagger CodegenWe can use multiple versions of Swagger Codegen as follows: // build.gradle
configurations {
swaggerCodegenV2
swaggerCodegenV3
}
dependencies {
swaggerCodegenV2 'io.swagger:swagger-codegen-cli:2.4.24'
swaggerCodegenV3 'io.swagger.codegen.v3:swagger-codegen-cli:3.0.30'
}
swaggerSources {
petstoreV2 {
inputFile = file('v2-petstore.yaml')
code {
language = 'spring'
configuration = configurations.swaggerCodegenV2
}
}
petstoreV3 {
inputFile = file('v3-petstore.yaml')
code {
language = 'spring'
configuration = configurations.swaggerCodegenV3
}
}
} See also the following examples: Configure Swagger UIWe can configure Swagger UI
by overwriting the default swaggerSources {
petstore {
inputFile = file('petstore.yaml')
ui {
doLast {
copy {
from 'index.html'
into outputDir
}
}
}
}
} You can create an
See also the following examples:
CompatibilitySwagger Codegen v3 and Java 16+To use Swagger Codegen v3 on Java 16 or later, you need to set swaggerSources {
petstore {
inputFile = file('petstore.yaml')
code {
language = 'html'
jvmArgs = ['--add-opens=java.base/java.util=ALL-UNNAMED'] // for Swagger Codegen v3 on Java 16+
}
}
} See #221 for details. SettingsThe plugin adds
Task type |
Key | Type | Value | Default value |
---|---|---|---|
inputFile |
File | Swagger spec file. | Mandatory |
reportFile |
File | File to write validation report. | $buildDir/tmp/validateSwagger/report.yaml |
It depends on the following JSON schema:
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 |
configuration |
String or Configuration | Configuration for Swagger Codegen | configurations.swaggerCodegen |
jvmArgs |
List of Strings | Arguments passed to jvm | None |
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.
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 |
title |
String | HTML title. | ReDoc - $filename |
options |
Map of Strings | ReDoc tag attributes. | Empty map |
This is an open source software licensed under the Apache License Version 2.0. Feel free to open issues or pull requests.
CI requires the following variables.
Environment Variable | Purpose |
---|---|
$GRADLE_PUBLISH_KEY |
Publish the plugin to Gradle Plugins |
$GRADLE_PUBLISH_SECRET |
Publish the plugin to Gradle Plugins |
2023-10-27
2022-08-15
2022-08-17
2022-09-23
2022-08-13
请发表评论