spring boot 结合 swagger 和 asciidoctor 生成接口文档

记录备忘

依赖配置

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