1.在項目的的pom文件中引入依賴和插件
<?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梯刚。
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();
? ? }
}
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.執(zhí)行mvn package -Dmaven.test.skip=true芯砸，生成的接口文檔在項目的target/asciidoc/pdf
！Ｚ逡薄！最后滥嘴，asciidoctor-maven-plugin插件對中文的支持不夠友好木蹬，可能會出現(xiàn)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.修改完成之后晦譬，保存，再去執(zhí)行生成命令mvn package -Dmaven.test.skip=true
