int128/gradle-swagger-generator-plugin: Gradle plugin for OpenAPI YAML validatio ...

原作者: [db:作者] 来自: 网络收藏邀请

开源软件名称（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 Plugin

Table of content

Introduction
Code Generation
Document Generation
- Swagger UI
- ReDoc
- HTML
Recipes
Compatibility
- Swagger Codegen v3 and Java 16+
Settings
Contributions

Introduction

This is a Gradle plugin for the following tasks:

Validate an OpenAPI YAML.
Generate source from an OpenAPI YAML using Swagger Codegen v2/v3 and OpenAPI Generator v3.
Generate Swagger UI with an OpenAPI YAML.
Generate ReDoc with an OpenAPI YAML.

See also the following examples:

Swagger UI example (generated by ui-v3/basic project)
ReDoc example (generated by redoc/basic project)
HTML document example (generated by codegen-v2/html project)
HTML document example (generated by codegen-v3/html project)
HTML document example (generated by openapi-v3/html project)

Code Generation

Create 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 build/swagger-code-petstore.

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

Document Generation

Swagger UI

Create 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 build/swagger-ui-petstore.

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

ReDoc

Create 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 build/redoc-petstore.

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

HTML

Create 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 build/swagger-code-petstore.

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

Recipes

See the example projects in acceptance-test.

Use configuration file

We can use a JSON configuration file as follows:

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

config.json depends on the language and framework. For example,

{
  "library": "spring-mvc",
  "modelPackage": "example.model",
  "apiPackage": "example.api",
  "invokerPackage": "example"
}

Run the task with Help postfix to show available 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
...

Build generated code

It is recommended to generate code into an ephemeral directory (e.g. build) and exclude it 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"

See also the following examples:

Validate YAML before code generation

It 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 generation

We 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']
    }
  }
}

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]

See selective generation section for details.

Use 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')
  }
}

See also the following examples:

Use 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'
    }
  }
}

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 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'
  }
  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 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"

See also the following examples:

Switch version of Swagger Codegen

We 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 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.

See also the following examples:

ui-v3/basic
ui-v2/basic (if you need Swagger UI 2.x)

Compatibility

Swagger Codegen v3 and Java 16+

To use Swagger Codegen v3 on Java 16 or later, you need to set jvmArgs as follows:

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.

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`

It depends on the following JSON schema:

OpenAPI Specification version 2.0

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
`configuration`	String or Configuration	Configuration for Swagger Codegen	`configurations.swaggerCodegen`
`jvmArgs`	List of Strings	Arguments passed to jvm	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`
`title`	String	HTML title.	`ReDoc - $filename`
`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.

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

鲜花

握手

雷人

路过

鸡蛋

该文章已有0人参与评论

请发表评论

全部评论

专题导读

More+

10-27 六六分期app的软件客服如何联系？(六六分期

11-06 可心卡盟:win10系统火狐flash插件崩溃怎么

11-06 亲亲特价:怎么删除回收站图标

11-06 济南大学虚拟社区:鲁大师节能降温的具体办

11-06 xlueops.exe:无线网络安装向导

11-06 女斗合众国:win7系统cf与主机连接不稳定怎

11-06 0xc000022-[cf烟雾头]cf怎么调烟雾头

11-06 qizideyouhuo:应用程序无法正常启动0xc0000

11-06 ipz-185:win7系统vcf文件怎么打开

11-06 傻哥蹦迪:win10系统s4怎么打开usb调试

11-06 八神浩树gtaste:回收站清空了怎么恢复

11-06 妖尾之黑色守护:win10系统电脑没有1440x900

11-06 校园至尊魔王小说:win7系统浏览网页时字体

11-06 女斗合众国:win10系统访问共享文件夹提示请

11-06 tokyo hot n0654:恢复win7系统默认字体一招

11-06 雨酷仙境:设置win7系统转移临时文件夹腾出

11-06 阿穆纳伊之杖:win7系统开始菜单在右边还原

11-06 tunespotting:win10系统火狐flash插件总是

11-06 甘尔葛分析师：计谋网站seo关键词暴涨有什

11-06 蔡贵霖: 计谋网站seo关键词暴涨有什么秘密

11-06 博益网首页:ao3网页版进入不了解决方法

11-06 漏斗子专栏: 网站数据分析小白易懂精华篇

11-06 见证双虹怎么做:win7系统开启telnet命令的

11-06 颾狐蝶蜋:系统资源不足无法完成请求的服务

11-06 国光中学校歌:提交网站到alexa查询详细步骤

11-06 西安有情天:静态网页和动态网页的区别

11-06 红木雅尚斋:外部链接构造对网站的好处

11-06 前官礼遇：防止域名劫持–增强域安全性的10

11-06 密传二转答案: 中文分词算法有哪些

11-06 金泉家园邮编:百度快照劫持的表现及应对方

GoogleCloudPlatform/gradle-appengine-plugin: Gradle plugin that provides tasks f ...发布时间：2022-06-18

qbeenslee/gradle-proguard-dictionary: A replica of wandoujia proguard dictionary发布时间：2022-06-18

剪的笔顺,诠释剪的笔画,认识剪的部首

1 六六分期app的软件客服如何联系？(六六分期

六六分期app的软件客服如何联系？不知道吗？加qq群【895510560】即可！标题：六六分期

阅读：18165|2023-10-27

2 可心卡盟:win10系统火狐flash插件崩溃怎么

今天小编告诉大家如何处理win10系统火狐flash插件总是崩溃的问题，可能很多用户都不知

阅读：9639|2022-11-06

3 亲亲特价:怎么删除回收站图标

今天小编告诉大家如何对win10系统删除桌面回收站图标进行设置，可能很多用户都不知道

阅读：8164|2022-11-06

4 济南大学虚拟社区:鲁大师节能降温的具体办

今天小编告诉大家如何对win10系统电脑设置节能降温的设置方法，想必大家都遇到过需要

阅读：8541|2022-11-06

5 xlueops.exe:无线网络安装向导

我们在使用xp系统的过程中,经常需要对xp系统无线网络安装向导设置进行设置，可能很多

阅读：8443|2022-11-06

6 女斗合众国:win7系统cf与主机连接不稳定怎

今天小编告诉大家如何处理win7系统玩cf老是与主机连接不稳定的问题，可能很多用户都不

阅读：9364|2022-11-06

7 0xc000022-[cf烟雾头]cf怎么调烟雾头

电脑对日常生活的重要性小编就不多说了，可是一旦碰到win7系统设置cf烟雾头的问题，很

阅读：8414|2022-11-06

8 qizideyouhuo:应用程序无法正常启动0xc0000

我们在日常使用电脑的时候，有的小伙伴们可能在打开应用的时候会遇见提示应用程序无法

阅读：7851|2022-11-06

9 ipz-185:win7系统vcf文件怎么打开

今天小编告诉大家如何对win7系统打开vcf文件进行设置，可能很多用户都不知道怎么对win

阅读：8397|2022-11-06

10 傻哥蹦迪:win10系统s4怎么打开usb调试

今天小编告诉大家如何对win10系统s4开启USB调试模式进行设置，可能很多用户都不知道怎

阅读：7389|2022-11-06

客服电话

电子邮件

int128/gradle-swagger-generator-plugin: Gradle plugin for OpenAPI YAML validatio ...

开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

Gradle Swagger Generator Plugin

Table of content

Introduction

Code Generation

Document Generation

Swagger UI

ReDoc

HTML

Recipes

Use configuration file

Build generated code

Validate YAML before code generation

Selective generation

Use custom template

Use custom generator class

Externalize template or generator class

Use multiple sources

Switch version of Swagger Codegen

Configure Swagger UI

Compatibility

Swagger Codegen v3 and Java 16+

Settings

Task type ValidateSwagger

Task type GenerateSwaggerCode

Task type GenerateSwaggerUI

Task type GenerateReDoc

Contributions

请发表评论

全部评论

上一篇：

下一篇：

CVE-2022-33677

apache/apisix-ingress-controller: APISIX

librespeed/speedtest: Self-hosted Speedt

avehtari/BDA_m_demos: Bayesian Data Anal

四维彩超怎么看性别？四维看男孩女孩诀窍

剪的笔顺,诠释剪的笔画,认识剪的部首

六六分期app的软件客服如何联系？(六六分期

florent37/ViewAnimator: A fluent Android

florent37/Shrine-MaterialDesign2: implem

CVE-2020-36276

SimpleSoftwareIO/simple-sms: Send and re

关于我们

产品与服务

解决方案

139-2527-9053

Task type `ValidateSwagger`

Task type `GenerateSwaggerCode`

Task type `GenerateSwaggerUI`

Task type `GenerateReDoc`