SpringBoot集成Swagger2—导出接口文档html和pdf格式（包含解决pdf中文部分缺失）

方法一（复杂）

导入jar包

注意swagger 版本在小于等于2.6会报错。swagger2markup不兼容

        <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>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>

插件

  <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.24</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>src/docs/generated/ascii</sourceDirectory>
                    <sourceHighlighter>coderay</sourceHighlighter>
                        <attributes>
                            <!--菜单栏在左边-->
                            <toc>left</toc>
                            <!--多标题排列-->
                            <toclevels>3</toclevels>
                            <!--自动打数字序号-->
                            <sectnums>true</sectnums>
                        </attributes>
<!--                    <attributes>-->
<!--                        <toc>left</toc>-->
<!--                    </attributes>-->
                </configuration>
                <!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
                <!--生成html-->
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>src/docs/generated/html</outputDirectory>
                        </configuration>
                    </execution>
                    <!--生成pdf-->
                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                        <!--生成路径-->   
                          <outputDirectory>src/docs/generated/pdf</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

解决pdf中文部分缺失

插件中的asciidoctorj-pdf包会造成pdf文件中文部分缺失
【0】 下载ttf文件.
设置了零积分下载的，应该是不需要积分了吧，不是很清楚。也可以自己百度下载
【1】找到jar包：
我的路径在：D:\maven\repository\org\asciidoctor\asciidoctorj-pdf\1.5.0-alpha.10.1下面（找到自己的jar包）

找到jar之后，打开字体文件路径：asciidoctorj-pdf-1.5.0-alpha.10.1.jar\gems\asciidoctor-pdf-1.5.0.alpha.10\data\fonts

【2】替换字体文件
在fonts下面有以.ttf结尾的字体文件，在themes下面是指定主题的配置文件，使用哪个字体文件，就是在这里指定的，我们先把自己下载好的字体文件加进去：

【3】修改主题配置文件
再修改asciidoctorj-pdf-1.5.0-alpha.10.1.jar\gems\asciidoctor-pdf-1.5.0.alpha.10\data\themes下面的default-theme.yml配置文件：

测试类

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

import java.net.URL;
import java.nio.file.Paths;

@SpringBootTest
@RunWith(SpringRunner.class)
public class swaggerTest {
    private final String swaggerUrl = "http://localhost:8091/v2/api-docs";

    /**
     * 生成AsciiDocs格式文档
     *
     * @throws Exception
     */
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(swaggerUrl))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/generated/ascii"));
    }

    /**
     * 生成Markdown格式文档
     *
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocs() throws Exception {
        //    输出Markdown格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(swaggerUrl))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/generated/markdown"));
    }

        /**
         * 生成AsciiDocs格式文档,并汇总成一个文件
         * @throws Exception
         */
        @Test
        public void generateAsciiDocsToFile () throws Exception {
            //    输出Ascii到单文件
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                    .withOutputLanguage(Language.ZH)
                    .withPathsGroupedBy(GroupBy.TAGS)
                    .withGeneratedExamples()
                    .withoutInlineSchema()
                    .build();

            Swagger2MarkupConverter.from(new URL(swaggerUrl))
                    .withConfig(config)
                    .build()
                    .toFile(Paths.get("src/docs/generated/ascii/all")); //all表示的是文件名
        }

        /**
         * 生成Markdown格式文档,并汇总成一个文件
         * @throws Exception
         */
        @Test
        public void generateMarkdownDocsToFile () throws Exception {
            //    输出Markdown到单文件
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                    .withOutputLanguage(Language.ZH)
                    .withPathsGroupedBy(GroupBy.TAGS)
                    .withGeneratedExamples()
                    .withoutInlineSchema()
                    .build();

            Swagger2MarkupConverter.from(new URL(swaggerUrl))
                    .withConfig(config)
                    .build()
                    .toFile(Paths.get("src/docs/generated/markdown/all")); //all表示的是文件名
        }


}

一般需求点击generateAsciiDocsToFile 方法就好。相应的目录要存在

运行步骤：

1. 测试类的：generateAsciiDocsToFile 方法
2. mvn asciidoctor:process-asciidoc
3. mvn generate-resources

方法二（简单）

如果方法一实在不行或者嫌太麻烦可以尝试一下简单的方法：最简单的导出方法.