使用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配置，注意红色字体的配置：

    
        
            org.springframework.boot
            spring-boot-maven-plugin
        

        
        
            io.github.swagger2markup
            swagger2markup-maven-plugin
            ${swagger2markup.version}
            
                
                    io.github.swagger2markup
                    swagger2markup-import-files-ext
                    ${swagger2markup.extension.version}
                
                
                    io.github.swagger2markup
                    swagger2markup
                    ${swagger2markup.version}
                
            
            
                
                ${swagger.input}
                ${generated.asciidoc.directory}
                
                    
                    ASCIIDOC
                    
                    TAGS
                    
                    
                
            
            
                
                    generate-resources
                    
                        convertSwagger2markup
                    
                
            
        
        
        
            org.asciidoctor
            asciidoctor-maven-plugin
            1.5.3
            
            
                
                    org.asciidoctor
                    asciidoctorj-pdf
                    1.5.0-alpha-zh.16
                

                
                
                    org.jruby
                    jruby-complete
                    9.1.8.0
                
                
                
                    org.asciidoctor
                    asciidoctorj
                    1.5.4
                
            
            
            
                
                ${asciidoctor.input.directory}
                
                
                
                    book
                    left
                    3
                    
                    
                    
                    
                    ${generated.asciidoc.directory}
                
            
            
            
                
                    output-html
                    generate-resources
                    
                        process-asciidoc
                    
                    
                        html5
                        ${asciidoctor.html.output.directory}
                        coderay
                    
                
                
                
                    output-pdf
                    generate-resources
                    
                        process-asciidoc
                    
                    
                        pdf
                        ${asciidoctor.pdf.output.directory}
                        
                        ${asciidoctor.input.directory}
                        
                        
                        coderay
                        book
                        
                            left
                            3
                            
                            
                            
                            
                            ${generated.asciidoc.directory}
                            fonts
                            themes
                            cn
                        
                    
                
            
        
    

第二种解决方案是把字体和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里有一行有点问题，改成http://${custom.baseurl}/v2/api-docs即可。
生成方式：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