[Swagger] 利用Gradle插件解析 swagger.json 并生成静态接口文档

利用Gradle插件解析 swagger.json 并生成静态接口文档

目录结构

|- capsule-static-doc
   |- docs
      |- asciidoc
         |- api
            |- index.doc
            |- astart.doc
         |- common
            |- index.doc
         |- resources 图片等静态资源目录
  			|- images
   |- resources 接口文件json目录
      |- xxx-api-v1.json
   |- src
      |- main
        |- java
        |- resources
      |- test
        |- java
        |- resources
   |- build.gradle
   |- README.md

build.gradle文件配置

buildscript {
    repositories {
        maven { url = 'http://af.hikvision.com.cn:80/artifactory/maven-down/' }
        maven { url 'http://maven.aliyun.com/nexus/content/groups/public/' }
        maven { url "https://plugins.gradle.org/m2/" }
        jcenter()
    }
    dependencies {
        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'
    }
}

apply plugin: 'java'
apply plugin: 'idea'
apply plugin: 'groovy'
apply plugin: 'org.asciidoctor.convert'
apply plugin: 'io.github.swagger2markup'

dependencies {
    //compile project(":capsule-common")
    compile libs["swagger2markup"]
    compile libs["groovy-all"]
}
ext {
    asciiDocOutputDir = file("${buildDir}/asciidoc/generated/" + getRestGroupName())
    swaggerOutputDir = file("${buildDir}/swagger")
    springfoxVersion = '2.5.0'
}
/**利用swagger2markup生成asciidoc文件*/
convertSwagger2markup {
    swaggerInput "${swaggerOutputDir}/" + getRestGroupName() + ".json"
    outputDir asciiDocOutputDir
    config = [
            'swagger2markup.markupLanguage': 'ASCIIDOC',
            'swagger2markup.generatedExamplesEnabled': true,
            'swagger2markup.pathsGroupedBy': 'TAGS',
            'swagger2markup.outputLanguage': 'EN']
}

/**利用asciidoc文件生成静态文档*/
asciidoctor {
    dependsOn convertSwagger2markup
    sourceDir = file("docs/asciidoc/"+getStaticPartName())
    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()
    }
}

asciidoctor.doFirst {
    println "clearCacheDocs starting..."
    clearCacheDocs
}

/**复制静态文件到指定目录并修改名称*/
asciidoctor.doLast {
    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"
    }

    copy {
        from "docs/asciidoc/resources"
        into "${buildDir}/rest-docs/" + getRestGroupName() + "/resources"
        include "**/*.png"
    }
}

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

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

def getStaticPartName() {
    return project.hasProperty('_static') ? ext._static : 'api'
}

/**打包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
    doLast {
        println getRestGroupName() + "接口文档生成成功！"
    }
}

//初始化目录
task initSwaggerFolder {
    println 'initSwaggerFolder'
    def swaggerJSONFolder = new File("${buildDir}/swagger")
    if (!swaggerJSONFolder.exists()) {
        swaggerJSONFolder.mkdirs()
    }
    copy {
        from "/resources"
        into "${buildDir}/swagger"
        include "*.json"
    }
}


//环境兼容 gradle wrapper
task wrapper(type: Wrapper){
    gradleVersion = '4.7'
    distributionType = 'all' //(可以下载gradle的all包)
}

Gradle Command Line

默认分组 xxx-api-v1 默认静态文件 api

gradle createStaticDoc

指定接口分组和静态接口文件

 gradle createStaticDoc -P_rest=xxx-ui-v1 -P_static=common

删除并打包 zip

 gradle archiveReports

Code Example

动态传入参数

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

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

REFRENCES

Swagger

1. Github Swagger2Markup/swagger2markup
2. swagger2markup 官方使用手册
3. asciidoctor/asciidoctor-gradle-plugin
4. 插件配置手册

Gradle

1. 彻底理解Gradle的任务
2. 创建 Gradle Plugin
3. Gradle系列教程 W3Cschool
4. Gradle从入门到实战 - Groovy基础
5. Gradle深入与实战（四）自定义集成测试任务
6. Gradle命令行黑魔法
7. Groovy 线程
8. Gradle 教程说明 用户指南 1~6章
9. Gradle的执行顺序
10. gradle 之 zip
11. Gradle-gradlew

Spring Boot

1. 泛型定义
2. Java判断对象是否为某一类型的实例
3. javaBean与Map<String,Object>互转
4. spring boot(5)-properties参数配置
5. 第三篇: spring-boot中的读取配置文件
6. Spring-boot中读取核心配置文件application和自定义properties配置文件的方式
7. 在SpringBoot下读取自定义properties配置文件的方法
8. Spring Boot干货系列：（二）配置文件解析