1.在项目的的pom文件中引入依赖和插件
pom.xml
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
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中
// 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