[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乾貨系列：（二）配置檔案解析