从官方文档中可以看到支持的语言默认有EN, DE, FR, RU。没错，不支持CN，从导出的文档也可以看到，部分中文无法显示，目前我也尚未找到是否有配置可以实现这个功能。网上的文章部分是通过替换源代码包里面的字体文件来实现，但是由于后面有更好的解决方案，这里就不再讨论。
从asciidoctorj-pdf的1.5.0-alpha.16版本以后（目前最新是1.5.0-alpha.18），这种方式生成文件会抛出异常，我个人并没有深究这个异常，有兴趣的读者可以通过修改版本号试一试。
生成的adoc文件一般包含overview.adoc、paths.adoc、definitions.adoc、security.adoc一共4个文件，这也是为什么要手动编写index.adoc进行整合的原因，感觉不太方便。
综上，我个人并不推荐采用此方式生成PDF。
build.gradle完整文件参考：
buildscript { ext { springbootVersion = '2.1.6.RELEASE' } repositories { maven { url 'http://maven.aliyun.com/nexus/content/groups/public' } } dependencies { classpath "org.springframework.boot:spring-boot-gradle-plugin:${springbootVersion}" classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.3' classpath 'io.github.swagger2markup:swagger2markup-gradle-plugin:1.3.3' } } repositories { maven { url 'http://maven.aliyun.com/nexus/content/groups/public' } } apply plugin: 'java' apply plugin: 'maven' apply plugin: 'org.springframework.boot' apply plugin: 'io.spring.dependency-management' apply plugin: 'io.github.swagger2markup' apply plugin: 'org.asciidoctor.convert' group 'com.jptangchina' version '1.0-SNAPSHOT' sourceCompatibility = 1.8 targetCompatibility = 1.8 ext { asciiDocOutputDir = file("${buildDir}/asciidoc") swaggerOutputDir = file("${buildDir}/swagger") swaggerVersion = '2.9.2' } dependencies { compile 'org.springframework.boot:spring-boot-starter-web' compile "io.springfox:springfox-swagger2:${swaggerVersion}" compile "io.springfox:springfox-swagger-ui:${swaggerVersion}" compile 'io.github.swagger2markup:swagger2markup:1.3.3' asciidoctor 'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.16' testCompile 'org.springframework.boot:spring-boot-starter-test' testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc' } test { systemProperty 'io.springfox.staticdocs.outputDir', swaggerOutputDir } convertSwagger2markup { dependsOn test swaggerInput "${swaggerOutputDir}/swagger.json" outputDir asciiDocOutputDir config = [ 'swagger2markup.pathsGroupedBy' : 'TAGS', ] } asciidoctor { dependsOn convertSwagger2markup sourceDir(asciiDocOutputDir.absolutePath) sources { include "index.adoc" } backends = ['pdf'] attributes = [ doctype: 'book', toc: 'left', toclevels: '3', numbered: '', sectlinks: '', sectanchors: '', hardbreaks: '', generated: asciiDocOutputDir ] } task genPdf(type: Test, dependsOn: test) { include '**/*SwaggerTest.class' exclude '**/*' dependsOn(asciidoctor) } 使用asciidoctor-gradle-plugin生成PDF（推荐）asciidoctor-gradle-plugin也是官方推荐的使用方式。相对前面的方式，使用起来更加简单，也可以修改配置输出中文。
1. 引入插件 plugins { id 'org.asciidoctor.jvm.pdf' version '2.2.0' } 2. 编写测试类生成adoc与第一中方法不同的是，不需要再将json文件保存到本地了。
@RunWith(SpringRunner.class) @SpringBootTest @AutoConfigureMockMvc public class SwaggerTest { @Autowired private MockMvc mockMvc; @Test public void generateAsciiDocsToFile() throws Exception { String outputDir = System.getProperty("io.springfox.staticdocs.outputDir"); MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs") .accept(MediaType.APPLICATION_JSON)) .andExpect(status().isOk()) .andReturn(); Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); MockHttpServletResponse response = mvcResult.getResponse(); String swaggerJson = response.getContentAsString(); Swagger2MarkupConverter.from(swaggerJson) .withConfig(config) .build() .toFile(Paths.get(outputDir + "/swagger")); } }有兴趣的读者可以阅读下toFile方法的源码，里面对第一种方法生成的4个文件进行了整合，这也是不再需要手动编写index.adoc文件的原因。
3. 配置asciidoctorPdf ext { asciiDocOutputDir = file("${buildDir}/asciidoc") // 创建字体与主题的文件夹 pdfFontsDir = file("${buildDir}/fonts") pdfThemesDir = file("${buildDir}/themes") swaggerVersion = '2.9.2' } pdfThemes { local 'basic', { styleDir = pdfThemesDir // styleName会被程序用于匹配${styleName}-theme.yml，如default-styleName-theme.yml styleName = 'default' } } asciidoctorPdf{ sourceDir(asciiDocOutputDir.absolutePath) sources { include "swagger.adoc" } fontsDir(pdfFontsDir.absolutePath) theme("basic") }本文字体与主题文件均来自于asciidoctorj-pdf-1.5.0-alpha.18.jar源码包，其路径位于：gems/asciidoctorj-pdf-1.5.0-alpha.18/data
4. 复制并修改default-theme.yml文件配置为了解决中文无法显示的问题，首先需要自行下载一个支持中文的字体文件。