跟着JHipster学做项目(2) - 使用Swagger2生成API文档（下）生成中文html5, PDF文件

本文链接：https://blog.youkuaiyun.com/java_augur/article/details/109123773

该博客介绍了如何通过asciidoctor-maven-plugin将Swagger的asciidoc文件转换为HTML5和PDF文档。配置了maven插件的依赖和执行阶段，并特别提到了生成中文文档时需要解决字体问题，包括添加中文字符集到字体目录及修改默认主题配置。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

上篇已经通过引入springfox-staticdocs成功生成了swagger的asciidoc文件，用浏览器来查看asciidoc文档需要安装插件，通常我们会进一步把asciidoc文件转化为html5, 或者PDF文档。

主要的功能由asciidoctor-maven-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.6</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.16</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>${asciidoctor.input.directory}</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>test</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
                        </configuration>
                    </execution>

                    <execution>
                        <id>output-pdf</id>
                        <phase>test</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
                        </configuration>
                    </execution>

                </executions>
            </plugin>

其中asciidoctorj-pdf， jruby-complete用于PDF文档生成，如果仅生成html5不需要引入这两个包。

<phase>test</phase>，这个配置只需要用maven执行test任务就可以生成文档。

另外一个重点在于生成中文文档，默认的asciidoctorj-pdf包中不包含中文字符集，所以会以日文字符生成缺字的文档。

在asciidoctorj-pdf-1.5.0-alpha.15.jar\gems\asciidoctor-pdf-1.5.0.alpha.15\data\fonts这个路径下加入中文字符集，例如：

Deng.ttf，Dengb.ttf， Dengl.ttf，在这里可以下载字符集。

在asciidoctor-pdf-1.5.0.alpha.15\data\themes路径下，编辑default-theme.yml文件

将字符集指向加入的中文字符集：

 normal: Deng.ttf
      bold: Dengb.ttf
      italic: Dengl.ttf
      bold_italic: Dengl.ttf

Good Luck,

Cheers!