記錄備忘

依賴配置

buildscript {
    repositories {
        maven { url "https://maven.aliyun.com/repository/gradle-plugin" }
        maven { url "https://maven.aliyun.com/repository/public" }
        mavenCentral()
    }
    dependencies {
        ...
        classpath("org.asciidoctor:asciidoctor-gradle-jvm:3.3.2")
    }
}

...
apply plugin: "org.asciidoctor.jvm.convert"

...
asciidoctor {
    sourceDir file('src/docs')   //接口描述文件讀取目錄
    outputDir file('build/docs') //接口文檔文件生成目錄 
    asciidoctorj {
        attribute("toc", "left")
        attribute("toclevels", "3")
        attribute("sectnums", true)
    }
}

dependencies {
    ...
    //  swagger2 
    def swagger_version = "2.9.2"
    implementation("io.springfox:springfox-swagger2:${swagger_version}")
    implementation("io.springfox:springfox-swagger-ui:${swagger_version}")
    // 通過跑測試程序來生成接口描述文件,所以只需要添加測試依賴即可
    testImplementation("io.github.swagger2markup:swagger2markup:1.3.3")
}

原理流程

asciidoctor 是將一些標記類語言(比如markdown(.md),asciidoc(.adoc)) 的文本文件生成 html的一個庫,那么我們要做的其實就是將 swagger 的接口描述信息轉換成對應的文件即可, 這中間就是利用到了 swagger 自身的接口和 swagger2markup 這個庫用來將接口信息轉成對應的文件 .adoc ,然后利用 asciidoctor (構建插件會生成同名的gradle task) 最后生成html文檔,最后利用chrome的打印功能生成pdf

測試類代碼

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc
public class BaseTest {

    @Resource
    protected MockMvc mockMvc;

    /**
    * json 轉 asciidoc , 生成文件路徑是 asciidoc 自身配置的 (參考上面的依賴配置)
    */
    @Test
    public void createSpringFoxSwaggerJson() throws Exception {
        System.out.println("============================= 開始生成接口ASCII文檔 =============================");
        //MediaType.APPLICATION_JSON沒有對字符編碼進行設置，采用默認值，MockHttpServletResponse默認字符編碼為ISO-8859-1
        MvcResult mvcResult = mockMvc.perform(MockMvcRequestBuilders.get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON_UTF8))
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andReturn();
        MockHttpServletResponse response = mvcResult.getResponse();
        String swaggerJson = response.getContentAsString();
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
        Swagger2MarkupConverter.from(swaggerJson)
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/asciidoc/generated/index"));
        System.out.println("============================= 生成接口ASCII文檔完成 =============================");
    }
}

該測試運行完成之后會在 src/docs/asciidoc/generated/ 目錄生成 index.adoc 文件

生成文檔文件

./gradlew asciidoctor --info

執行完成之后在 build/docs (參考上面的配置) 目錄生成最后的html靜態資源文件

參考資料

user-guide