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.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.8.0version>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.8.0version>
        dependency>

        
        <dependency>
            <groupId>io.github.swagger2markupgroupId>
            <artifactId>swagger2markupartifactId>
            <version>1.3.1version>
        dependency>
        

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

            <plugin>
                <groupId>io.github.swagger2markupgroupId>
                <artifactId>swagger2markup-maven-pluginartifactId>
                <version>1.2.0version>
                <configuration>
                    
                    <swaggerInput>http://localhost:8082/v2/api-docsswaggerInput>
                    <outputDir>src/docs/asciidoc/generatedoutputDir>
                    <config>
                        
                        <swagger2markup.markupLanguage>ASCIIDOCswagger2markup.markupLanguage>
                    config>
                configuration>
            plugin>

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

            <plugin>
                <groupId>org.asciidoctorgroupId>
                <artifactId>asciidoctor-maven-pluginartifactId>
                <version>1.5.3version>
                
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctorgroupId>
                        <artifactId>asciidoctorj-pdfartifactId>
                        <version>1.5.0-alpha.10.1version>
                    dependency>
                    <dependency>
                        <groupId>org.jrubygroupId>
                        <artifactId>jruby-completeartifactId>
                        <version>1.7.21version>
                    dependency>
                dependencies>
                
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generatedsourceDirectory>
                    <sourceHighlighter>coderaysourceHighlighter>
                    <attributes>
                        <toc>lefttoc>
                    attributes>
                configuration>
                
                <executions>
                    <execution>
                        <id>output-htmlid>
                        <phase>generate-resourcesphase>
                        <goals>
                            <goal>process-asciidocgoal>
                        goals>
                        <configuration>
                            <backend>html5backend>
                            <outputDirectory>src/docs/asciidoc/htmloutputDirectory>
                        configuration>
                    execution>

                    <execution>
                        <id>output-pdfid>
                        <phase>generate-resourcesphase>
                        <goals>
                            <goal>process-asciidocgoal>
                        goals>
                        <configuration>
                            <backend>pdfbackend>
                            <outputDirectory>src/docs/asciidoc/pdfoutputDirectory>
                        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/