swagger生成PDF接口文档

1.在项目的的pom文件中引入依赖和插件

pom.xml

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <!--jcenter仓库插件地址-->

    <pluginRepositories>

        <pluginRepository>

            <id>jcenter</id>

            <name>jcenter maven</name>

            <url>http://jcenter.bintray.com</url>

        </pluginRepository>

    </pluginRepositories>

    <properties>

        <!--swgger2markup 配置信息-->

        <swagger2markup.version>1.2.0</swagger2markup.version>

        <asciidoctor.input.directory>${project.basedir}/src/main/asciidoc</asciidoctor.input.directory>

        <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>

        <swagger.snippetOutput.dir>${project.build.directory}/generated-snippets</swagger.snippetOutput.dir>

        <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory>

        <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>

        <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>

        <swagger.input>${swagger.output.dir}/swagger.json</swagger.input>

    </properties>

    <!--生成swagger pdf文档配置地址-->

    <repositories>

        <repository>

            <id>jcenter-snapshots</id>

            <name>jcenter</name>

            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>

        </repository>

    </repositories>

    <dependencies>

        <!--swagger-->

        <dependency>

            <groupId>com.jet</groupId>

            <artifactId>ecss_swagger_starter</artifactId>

            <version>0.0.2-RELEASE</version>

        </dependency>

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger2</artifactId>

            <version>${springfox-version}</version>

        </dependency>

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger-ui</artifactId>

            <version>${springfox-version}</version>

        </dependency>

        <!--MOCKMVC配置-->

        <dependency>

            <groupId>org.springframework.restdocs</groupId>

            <artifactId>spring-restdocs-mockmvc</artifactId>

            <version>2.0.1.RELEASE</version>

            <scope>test</scope>

        </dependency>

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-data-rest</artifactId>

            <version>2.8.0</version>

        </dependency>

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-bean-validators</artifactId>

            <version>2.8.0</version>

        </dependency>

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-staticdocs</artifactId>

            <version>2.4.0</version>

        </dependency>

        <dependency>

            <groupId>io.github.robwin</groupId>

            <artifactId>assertj-swagger</artifactId>

            <version>0.2.0</version>

            <scope>test</scope>

        </dependency>

    </dependencies>

    <dependencyManagement>

        <dependencies>

            <dependency>

                <groupId>org.springframework.cloud</groupId>

                <artifactId>spring-cloud-dependencies</artifactId>

                <version>${spring-cloud.version}</version>

                <type>pom</type>

                <scope>import</scope>

            </dependency>

        </dependencies>

    </dependencyManagement>

    <build>

        <plugins>

<!--设置swagger输出变量信息-->

            <plugin>

                <groupId>org.apache.maven.plugins</groupId>

                <artifactId>maven-surefire-plugin</artifactId>

                <configuration>

                    <systemPropertyVariables>

                        <io.springfox.staticdocs.outputDir>${swagger.output.dir}</io.springfox.staticdocs.outputDir>

                        <io.springfox.staticdocs.snippetsOutputDir>${swagger.snippetOutput.dir}</io.springfox.staticdocs.snippetsOutputDir>

                    </systemPropertyVariables>

                </configuration>

            </plugin>

            <!--asciidoc插件-->

            <plugin>

                <groupId>io.github.swagger2markup</groupId>

                <artifactId>swagger2markup-maven-plugin</artifactId>

                <version>${swagger2markup.version}</version>

                <dependencies>

                    <dependency>

                        <groupId>io.github.swagger2markup</groupId>

                        <artifactId>swagger2markup-import-files-ext</artifactId>

                        <version>${swagger2markup.version}</version>

                    </dependency>

                    <dependency>

                        <groupId>io.github.swagger2markup</groupId>

                        <artifactId>swagger2markup-spring-restdocs-ext</artifactId>

                        <version>${swagger2markup.version}</version>

                    </dependency>

                </dependencies>

                <configuration>

                    <swaggerInput>${swagger.input}</swaggerInput>

                    <outputDir>${generated.asciidoc.directory}</outputDir>

                    <config>

                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>

                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>

                        <swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/main/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>

                        <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/main/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>

                        <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/main/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>

                        <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/main/asciidoc/extensions/security/</swagger2markup.extensions.dynamicSecurity.contentPath>

                        <swagger2markup.extensions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}</swagger2markup.extensions.springRestDocs.snippetBaseUri>

                        <swagger2markup.extensions.springRestDocs.defaultSnippets>true</swagger2markup.extensions.springRestDocs.defaultSnippets>

                    </config>

                </configuration>

                <executions>

                    <execution>

                        <phase>test</phase>

                        <goals>

                            <goal>convertSwagger2markup</goal>

                        </goals>

                    </execution>

                </executions>

            </plugin>

            <!--Asciidoctor插件 -->

            <plugin>

                <groupId>org.asciidoctor</groupId>

                <artifactId>asciidoctor-maven-plugin</artifactId>

                <version>1.5.3</version>

                <!-- PDF依赖 -->

                <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>

                <!-- 生成文件时的配置信息 -->

                <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>

                    <!--生成html-->

                    <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>

                    <!--生成pdf-->

                    <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>

        </plugins>

    </build>

</project>

2.在项目的test目录中加入两个java类文件，加入后运行一次SwaggerTest.java，为了生成swagger.json，可到项目目录target\swagger中查看是否生成了swagger.json。

ControllerTest.java

package com.jet.ecss.contact.support;

import org.junit.Before;

import org.junit.Rule;

import org.junit.runner.RunWith;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;

import org.springframework.boot.test.context.SpringBootTest;

import org.springframework.restdocs.JUnitRestDocumentation;

import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;

import org.springframework.test.context.junit4.SpringRunner;

import org.springframework.test.web.servlet.MockMvc;

import org.springframework.test.web.servlet.setup.MockMvcBuilders;

import org.springframework.web.context.WebApplicationContext;

@SpringBootTest

@RunWith(SpringRunner.class)

@AutoConfigureMockMvc

public abstract class ControllerTest {

    protected MockMvc mockMvc;

    @Autowired

    protected WebApplicationContext context;

    @Rule

    public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();

    @Before

    public void setUp() {

        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)

                .apply(MockMvcRestDocumentation.documentationConfiguration(this.restDocumentation))

                .build();

    }

}

SwaggerTest.java

package com.jet.ecss.contact.support;

import org.junit.Test;

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import org.springframework.http.MediaType;

import java.io.BufferedWriter;

import java.nio.charset.StandardCharsets;

import java.nio.file.Files;

import java.nio.file.Paths;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;

import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

public class SwaggerTest extends ControllerTest {

    private final static Logger logger = LoggerFactory.getLogger(SwaggerTest.class);

    @Test

    public void createSwaggerJson() throws Exception {

        logger.info("------ 获取用于生成自动文档的swagger.json文件 ------");

        String swaggerJson = this.mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))

                .andExpect(status().isOk()).andReturn().getResponse().getContentAsString();

        // 对应pom.xml中 <systemPropertyVariables> 设置的属性值

//        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");

        String outputDir = "target/swagger";

        Files.createDirectories(Paths.get(outputDir));

        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) {

            writer.write(swaggerJson);

        }

        return;

    }

}

3.在项目main目录新建目录asciidoc，在里面新建一个index.adoc文件，文件内容如下

include::{generated}/overview.adoc[]

include::{generated}/paths.adoc[]

include::{generated}/security.adoc[]

include::{generated}/definitions.adoc[]

4.执行mvn package -Dmaven.test.skip=true，生成的接口文档在项目的target/asciidoc/pdf

！！！最后，asciidoctor-maven-plugin插件对中文的支持不够友好，可能会出现pdf中文的丢失或者乱码，需要对插件字体进行替换

1.在maven仓库中找到该jar包

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

3.在fonts下面有以.ttf结尾的字体文件，使用哪个字体文件，就是在这里指定的，先把自己下载好的字体文件加进去

4.修改asciidoctorj-pdf-1.5.0-alpha.10.1.jar\gems\asciidoctor-pdf-1.5.0.alpha.10\data\themes下面的default-theme.yml配置文件： 

5.修改完成之后，保存，再去执行生成命令mvn package -Dmaven.test.skip=true