spring boot2.0+swagger自动生成PDF和HTML格式的API文档

利用swagger自动生成PDF和HTML格式的API文档

前提

首先要有一个整合了swagger的spring boot项目，如果没有可以参考我的上一篇博客：Spring Boot 2.0整合Swagger2.8，在里面详细介绍了如果整合swagger，并通过swagger-ui查看接口相关信息。

依赖引入

首先需要在pom文件里面引入如下依赖：
第一部分是swagger所需的基本依赖和导出静态文档所需要的包：

    <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

        <!-- ********************* swagger导出PDF/HTML所需依赖 START ********************************* -->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>
        <!-- ********************* swagger导出PDF/HTML所需依赖 END ********************************* -->

第二部分需要添加的是生成ASCIIDOC所需要maven插件：

<!--此插件生成ASCIIDOC-->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.2.0</version>
                <configuration>
                    <!--此处端口一定要是当前项目启动所用的端口-->
                    <swaggerInput>http://localhost:8082/v2/api-docs</swaggerInput>
                    <outputDir>src/docs/asciidoc/generated</outputDir>
                    <config>
                        <!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>

第三部分需要添加输出PDF和HTML的maven插件：

<!--此插件生成HTML和PDF-->
            <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.10.1</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>src/docs/asciidoc/generated</sourceDirectory>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </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>src/docs/asciidoc/html</outputDirectory>
                        </configuration>
                    </execution>

                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                        </configuration>
                    </execution>

                </executions>
            </plugin>

运行指令

配置好后首先需要运行asciidoctor-maven-plugin插件的命令去生成adoc文件,再运行generate-resources命令输出静态文档，因为该插件是根据adoc文件生成的PDF和HTML，所以顺序不能错，最后输出的PDF文件会在src/docs/asciidoc/pdf目录下面。

mvn asciidoctor:process-asciidoc
mvn generate-resources

最后效果如图：

生成的HTML和PDF如下：
HTML：

PDF：

总结

至此，swagger已经帮我们自动生成了简单的接口文档，文档内容根据项目里面配置的注解的信息来生成，注解越详细，内容越完备，还可以根据接口字段信息的更新自动更新，而且格式也很美观，最重要的是再也不用自己动手写文档调格式了，可以说是极大的帮助程序员解放了生产力，妈妈再也不怕项目经理找我要文档了。
不过，可以看到的是，由于中文编码的问题，导致生成的PDF文件会有部分缺字漏字，对于追求完美的程序员来说，这肯定是不行的，所以，我会在下一篇博客里面解决这一问题。

参考信息

https://asciidoctor.org/docs/asciidoctor-maven-plugin/