Swagger 接口管理和文档导出 [Gradle + Spring Boot]

基于 Gradle (支持利用swagger.json和gradle命令行直接生成接口文档并完成打包) [项目内外使用皆可，但是需要是gradle进行构建的项目]

Gradle 配置 [spring boot]

buildscript {
    ext {
        springBootVersion = '2.0.5.RELEASE'
    }
    repositories {
        maven { url 'http://maven.aliyun.com/nexus/content/groups/public/' }
        maven { url "https://plugins.gradle.org/m2/" }
        jcenter()
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.8'
        classpath 'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.10.1'
        classpath 'io.github.swagger2markup:swagger2markup-gradle-plugin:1.2.0'
        classpath "info.robotbrain.gradle.lombok:lombok-gradle:1.1"
    }
}

apply plugin: 'java'
apply plugin: 'idea'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'
apply plugin: 'org.asciidoctor.convert'
apply plugin: 'io.github.swagger2markup'
apply plugin: "info.robotbrain.lombok"
apply plugin: 'groovy'

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = 1.8

repositories {
    maven { url 'http://maven.aliyun.com/nexus/content/groups/public/' }
    maven { url "https://plugins.gradle.org/m2/" }
    jcenter()
    mavenCentral()
}


dependencies {
    compileOnly('org.projectlombok:lombok')
    compile('org.springframework.boot:spring-boot-starter')
    compile 'org.codehaus.groovy:groovy-all:2.2.0'
    compile group: 'io.github.swagger2markup', name: 'swagger2markup', version: '1.3.3'
    compile group: 'org.springframework.boot', name: 'spring-boot-configuration-processor', version: '2.0.5.RELEASE'
    testCompile('org.springframework.boot:spring-boot-starter-test')
}

ext {
    asciiDocOutputDir = file("${buildDir}/asciidoc/generated/" + getRestGroupName())
    swaggerOutputDir = file("${buildDir}/swagger")
    springfoxVersion = '2.5.0'
}

/**利用swagger2markup生成asciidoc文件*/
convertSwagger2markup {
    dependsOn test
    swaggerInput "${swaggerOutputDir}/" + getRestGroupName() + ".json"
    outputDir asciiDocOutputDir
    config = [
            'swagger2markup.markupLanguage': 'ASCIIDOC',
            'swagger2markup.outputLanguage': 'EN']
}

/**利用asciidoc文件生成静态文档*/
asciidoctor {
    dependsOn convertSwagger2markup
    sources {
        include 'index.adoc'
    }
    backends = ['html5', 'pdf']
    attributes = [
            doctype    : 'book',
            toc        : 'left',
            toclevels  : '2',
            numbered   : '',
            sectlinks  : '',
            sectanchors: '',
            hardbreaks : '',
            generated  : asciiDocOutputDir
    ]
}

/**清空缓存文件*/
task clearCacheDocs {
    File htmlDir = file("${buildDir}/asciidoc/html5")
    File pdfDir = file("${buildDir}/asciidoc/pdf")
    if (htmlDir.exists()) {
        htmlDir.deleteDir()
    }
    if (pdfDir.exists()) {
        pdfDir.deleteDir()
    }
}


/**复制静态文件到指定目录并修改名称*/
task copyStaticDocsTask() {
    def docHasOut = false
    Thread.start("copyStaticDocsTask") {
        def docPdfDir = new File("${buildDir}/asciidoc/pdf")
        while (!docHasOut) {
            if (null != docPdfDir.listFiles() && docPdfDir.listFiles().length > 0) {
                Thread.currentThread().sleep(3000)
                docHasOut = true
                println "start copy to rest-docs folder..."
                copy {
                    from "${buildDir}/asciidoc/html5"
                    into "${buildDir}/rest-docs/" + getRestGroupName() + "/html5"
                    include "*.html"
                    rename {
                        String fileName ->
                            fileName.replace('index', getRestGroupName())
                    }
                }
                copy {
                    from "${buildDir}/asciidoc/pdf"
                    into "${buildDir}/rest-docs/" + getRestGroupName() + "/pdf"
                    include "*.pdf"
                    rename {
                        String fileName ->
                            fileName.replace('index', getRestGroupName())
                    }
                }
                copy {
                    from "${buildDir}/swagger/"
                    into "${buildDir}/rest-docs/" + getRestGroupName() + "/json"
                    include getRestGroupName() + "*.json"
                }
            }
        }
    }
}

/**获取时间戳*/
def getDate() {
    return new Date().format('yyyyMMddHHmm')
}

/**解析命令行参数：接口分组*/
def getRestGroupName() {
    return project.hasProperty('_rest') ? ext._rest : "xxx-api-v1"
}

/**打包ZIP*/
task archiveReports(type: Zip) {
    from "$buildDir/rest-docs"
    into "rest-docs-zip"
    baseName = "rest-docs-" + getDate()
    destinationDir file("$buildDir/rest-zip")
    doLast {
        delete "$buildDir/rest-docs"
    }
}


/**创建任务起点*/
task createStaticDoc {
      dependsOn asciidoctor
      doFirst {
          println "clearCacheDocs starting..."
          clearCacheDocs
      }
      doLast {
          println getRestGroupName()
          copyStaticDocsTask
      }
}

Gradle Command Line [使用方法]

swagger.json文件放在build/swagger目录下
使用gradle命令指定生成文件

gradle

- gradle createStaticDoc -P_rest="xxx-api-v1"

- gradle createStaticDoc -P_rest="xxx-ui-v1"
/**接口文档打包zip*/
- gradle archiveReports

gradlew

- ./gradlew createStaticDoc -P_rest="xxx-api-v1"
- ./gradlew copyStaticDoc -P_rest="xxx-api-v1"

- ./gradlew createStaticDoc -P_rest="xxx-ui-v1"
- ./gradlew archiveReports

Gralde动态传入参数实例

def validate() {
    return project.hasProperty('_param') ? ext._param : false
}

task showParam {
    println validate()
}
//命令行运行 gradle showParam -P_param=Abc

运行结果

E:\sync\spring-boot-samples\capsule-utils-web>gradle showParam -P_param=Abc

> Configure project :
Abc

BUILD SUCCESSFUL in 0s

REFERENCES

Spring Boot

Swagger

Gradle

扫码关注“架构探险之道”，回复文章名称获取更多源码和文章资源

知识星球(扫码加入获取源码和文章资源链接)