使用Swagger2Markup、asciidoctor-maven-plugin和asciidoctorj-pdf插件生成PDF格式的API文档中文问题解决

使用Swagger2Markup、asciidoctor-maven-plugin和asciidoctorj-pdf插件能生成pdf格式的文档，但是对于中文支持太差了，很多中文字符是空白。

参考 https://www.xncoding.com/2017/06/09/web/swagger.html，发现是中文字体的问题，但这个文章里说的解决方案比较麻烦，经过试验找到了简单的解决方案。

解决方案有两种：

一种是下载字体（RobotoMono 开头和 KaiGenGothicCN 开头的字体文件）和theme文件（Source code (zip)）。

字体下载链接：https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases

然后在项目的资源目录下创建fonts和themes两个目录，把下载的8个字体文件复制到fonts目录下，解压asciidoctor-pdf-cjk-kai_gen_gothic-0.1.0-fonts.zip文件，把data\themes\下的cn-theme.yml复制到themes目录下

pom.xml配置，注意红色字体的配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>

        <!-- First, use the swagger2markup plugin to generate asciidoc -->
        <plugin>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-maven-plugin</artifactId>
            <version>${swagger2markup.version}</version>
            <dependencies>
                <dependency>
                    <groupId>io.github.swagger2markup</groupId>
                    <artifactId>swagger2markup-import-files-ext</artifactId>
                    <version>${swagger2markup.extension.version}</version>
                </dependency>
                <dependency>
                    <groupId>io.github.swagger2markup</groupId>
                    <artifactId>swagger2markup</artifactId>
                    <version>${swagger2markup.version}</version>
                </dependency>
            </dependencies>
            <configuration>
                <!--The URL or file path to the Swagger specification-->
                <swaggerInput>${swagger.input}</swaggerInput>
                <outputDir>${generated.asciidoc.directory}</outputDir>
                <config>
                    <!--设置输出文件的语言：ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP-->
                    <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    <!--设置目录的展现方式-->
                    <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                    <!--扩展Overview的内容，可以增加一些自定义的内容-->
                    <!--<swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
                    <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
                    <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
                    <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security</swagger2markup.extensions.dynamicSecurity.contentPath>-->
                </config>
            </configuration>
            <executions>
                <execution>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>convertSwagger2markup</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <!-- Run the generated asciidoc through Asciidoctor to generate
             other documentation types, such as PDFs or HTML5 -->
        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.3</version>
            <!-- Include Asciidoctor PDF for pdf generation -->
            <dependencies>
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctorj-pdf</artifactId>
                    <version>1.5.0-alpha-zh.16</version>
                </dependency>

                <!-- Comment this section to use the default jruby artifact provided by the plugin -->
                <dependency>
                    <groupId>org.jruby</groupId>
                    <artifactId>jruby-complete</artifactId>
                    <version>9.1.8.0</version>
                </dependency>
                <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctorj</artifactId>
                    <version>1.5.4</version>
                </dependency>
            </dependencies>
            <!-- Configure generic document generation settings -->
            <configuration>
                <!--默认指向 ${basedir}/src/main/asciidoc-->
                <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
                <!--an override to process a single source file; 默认指向 ${sourceDirectory} 中的所有文件-->
                <!--<sourceDocumentName>index.adoc</sourceDocumentName>-->
                <attributes>
                    <doctype>book</doctype>
                    <toc>left</toc>
                    <toclevels>3</toclevels>
                    <numbered></numbered>
                    <hardbreaks></hardbreaks>
                    <sectlinks></sectlinks>
                    <sectanchors></sectanchors>
                    <generated>${generated.asciidoc.directory}</generated>
                </attributes>
            </configuration>
            <!-- Since each execution can only handle one backend, run
                 separate executions for each desired output type -->
            <executions>
                <execution>
                    <id>output-html</id>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>html5</backend>
                        <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
                        <sourceHighlighter>coderay</sourceHighlighter>
                    </configuration>
                </execution>
                <!-- 生成PDF,对中文字符的支持不完善 -->
                <execution>
                    <id>output-pdf</id>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>pdf</backend>
                        <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
                        <!--默认指向 ${basedir}/src/main/asciidoc-->
                        <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
                        <!--an override to process a single source file; 默认指向 ${sourceDirectory} 中的所有文件-->
                        <!--<sourceDocumentName>index.adoc</sourceDocumentName>-->
                        <sourceHighlighter>coderay</sourceHighlighter>
                        <doctype>book</doctype>
                        <attributes>
                            <toc>left</toc>
                            <toclevels>3</toclevels>
                            <numbered></numbered>
                            <hardbreaks></hardbreaks>
                            <sectlinks></sectlinks>
                            <sectanchors></sectanchors>
                            <generated>${generated.asciidoc.directory}</generated>
                            <pdf-fontsdir>fonts</pdf-fontsdir>
                            <pdf-stylesdir>themes</pdf-stylesdir>
                            <pdf-style>cn</pdf-style>
                        </attributes>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

第二种解决方案是把字体和themes文件放到jar包中，方便复用。

把文件放到asciidoctorj-pdf的jar的gems\asciidoctor-pdf-1.5.0.alpha.zh.16\data里飞fonts和themes目录下即可。

或者用我已经生成好的jar，csdn下载

如果没有csdn积分的话，可以到github上下载：github下载

生成示例项目（demo）下载

demo的pom.xml里有一行有点问题，改成<swagger.input>http://${custom.baseurl}/v2/api-docs</swagger.input>即可。
生成方式：1运行项目。2.在当前目录的命令行下执行mvn generate-resources

上传此jar到自己的maven私服，红色字体部分请按照自己的具体情况进行修改，如有疑问，请搜索maven上传jar到私服：

mvn deploy:deploy-file -Dfile=e:/asciidoctorj-pdf/1.5.0-alpha-zh.16/asciidoctorj-pdf-1.5.0-alpha-zh.16.jar -DgroupId=org.asciidoctor -DartifactId=asciidoctorj-pdf -Dversion=1.5.0-alpha-zh.16 -Dpackaging=jar -Durl=http://ip:8080/nexus/content/repositories/thirdparty/ -DrepositoryId=thirdparty