转自：https://blog.csdn.net/seanxwq/article/details/78064599
最近因为项目中需要编写接口文档，原来用的swagger结合现有项目问题比较多，且没有直观的目录（不知道swagger是否有左边栏目录这样的形式，没去细查），配合前端和测试使用时，他们抱怨比较多，所以摒弃了swagger之后，找到了spring rest docs， 结合官方文档和网上查到的资料，成功生成了接口文档。样例如下：
spring rest docs的使用其实就是在你现有的spring mvc或spring boot的项目上，配置生成文档的依赖包，然后编写接口单元测试，编写adoc配置文件，最后打包自动生成html接口文档的过程。根据这个步骤一步步操作：
1、配置依赖：
-
<dependency>
-
<groupId>org.springframework.restdocs
</groupId>
-
<artifactId>spring-restdocs-mockmvc
</artifactId>
-
<scope>test
</scope>
-
</dependency>
-
<build>
-
<plugins>
-
<plugin>
-
<groupId>org.springframework.boot
</groupId>
-
<artifactId>spring-boot-maven-plugin
</artifactId>
-
</plugin>
-
<plugin>
-
<groupId>org.asciidoctor
</groupId>
-
<artifactId>asciidoctor-maven-plugin
</artifactId>
-
<version>1.5.3
</version>
-
<executions>
-
<execution>
-
<id>generate-docs
</id>
-
<phase>prepare-package
</phase>
-
<goals>
-
<goal>process-asciidoc
</goal>
-
</goals>
-
<configuration>
-
<backend>html
</backend>
-
<doctype>book
</doctype>
-
</configuration>
-
</execution>
-
</executions>
-
<dependencies>
-
<dependency>
-
<groupId>org.springframework.restdocs
</groupId>
-
<artifactId>spring-restdocs-asciidoctor
</artifactId>
-
<version>1.2.1.RELEASE
</version>
-
</dependency>
-
</dependencies>
-
</plugin>
-
<plugin>
-
<artifactId>maven-resources-plugin
</artifactId>
-
<version>2.7
</version>
-
<executions>
-
<execution>
-
<id>copy-resources
</id>
-
<phase>prepare-package
</phase>
-
<goals>
-
<goal>copy-resources
</goal>
-
</goals>
-
<configuration>
-
<outputDirectory>
-
${project.build.outputDirectory}/static/docs</div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="45"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> <span class="hljs-tag"></<span class="hljs-name">outputDirectory</span>></span></div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="46"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> <span class="hljs-tag"><<span class="hljs-name">resources</span>></span></div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="47"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> <span class="hljs-tag"><<span class="hljs-name">resource</span>></span></div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="48"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> <span class="hljs-tag"><<span class="hljs-name">directory</span>></span></div></div></li><li><div class="hljs-ln-numbers"><div class="hljs-ln-line hljs-ln-n" data-line-number="49"></div></div><div class="hljs-ln-code"><div class="hljs-ln-line"> ${project.build.directory}/generated-docs
-
</directory>
-
</resource>
-
</resources>
-
</configuration>
-
</execution>
-
</executions>
-
</plugin>
-
</plugins>
-
</build>
我们通过mock进行接口测试编写，测试类属性配置及单测前的before方法：
-
@Rule
-
public JUnitRestDocumentation restDocumentation =
new JUnitRestDocumentation(
"target/generated-snippets");
//生成的adoc文件导出目录
-
private MockMvc mockMvc;
-
@Autowired
-
private WebApplicationContext context;
-
-
@Before
-
public void setUp() {
-
this.mockMvc = MockMvcBuilders.webAppContextSetup(
this.context)
-
.apply(documentationConfiguration(
this.restDocumentation))
-
// .alwaysDo(document("{method-name}/{step}/"))
-
.build();
-
}
-
@Test
-
public void contextLoads() throws Exception {
-
this.mockMvc.perform(get(
"/hello?page=2&per_page=100").accept(MediaType.APPLICATION_JSON).header(
"Authorization",
"Basic dXNlcjpzZWNyZXQ="))
-
.andDo(print()).andExpect(status().isOk())
-
.andDo(document("hello 接口",//这个identity不同的单测需要不同，否则其他的测试会覆盖现有的，最后文档里只生成一个接口说明
-
requestHeaders(
-
headerWithName(
"Authorization").description(
-
"Basic auth credentials")),
-
requestParameters(
-
parameterWithName(
"page").description(
"The page to retrieve"),
-
parameterWithName(
"per_page").description(
"Entries per page")
-
)));
-
}
在maven项目标准结构下，src/main下新建asciidoc目录，并建一个.adoc为结尾的文件（到时候打包时，会根据asciidoc目录下的所有.adoc文件生成过个对应文件名的html文档）。例子如下：
-
<span style=
"color:#ff6666;">== hello 接口</span>
-
.http-
request
-
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello 接口\http-
request.adoc[]
-
.
request-headers 请求头说明
-
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello 接口\
request-headers.adoc[]
-
.
request-parameters 请求参数说明
-
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello 接口\
request-parameters.adoc[]
-
.http-
response
-
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello 接口\http-
response.adoc[]
-
-
<span style=
"color:#ff6666;">== hello2 接口</span>
-
.http-
request
-
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello2 接口\http-
request.adoc[]
-
.http-
response
-
include::D:\ideaworkspace\restdoc\target\generated-snippets\hello2 接口\http-
response.adoc[]
以上是根据官网文档，就可以导出一个接口文档。但是，并没有左边栏的目录，而且写一个单测就要在.adoc文件里添加include关键字导入新生成的接口内容很麻烦，怎么办呢？
首先，左边栏目录或右边栏目录，或直接在文档最开头添加目录我们只需要在.adoc文件开头添加如下内容：
-
= 接口文档
-
v1
.0,
2017
-09
-22
-
:toc:
left
然后解决每写一个接口测试就要在.adoc文件里添加include的问题：
我们编写.adoc文件生成功能，方法如下（参考了：点击打开链接）：
-
@Test
-
public void adocBuild() throws IOException {
-
String appDir = System.getProperty(
"user.dir");
-
String adocPath = appDir +
"\src\main\asciidoc\hello.adoc";
-
StringBuilder content =
new StringBuilder();
-
content.append(
"include::" + appDir +
"\src\main\asciidoc\preview.adoc[]").append(System.getProperty(
"line.separator")).append(System.getProperty(
"line.separator"));
-
File apidirs =
new File(appDir +
"\target\generated-snippets");
-
for (File apidir : apidirs.listFiles()) {
-
String apiName = apidir.getName();
-
content.append(
"== " + apiName + System.getProperty(
"line.separator"));
-
fileAppend(content, apidir +
"\http-request.adoc",
".http-request");
-
fileAppend(content, apidir +
"\request-headers.adoc",
".request-headers 请求头说明");
-
fileAppend(content, apidir +
"\request-parameters.adoc",
".request-parameters 请求参数说明");
-
fileAppend(content, apidir +
"\request-body.adoc",
".request-body 请求体说明");
-
fileAppend(content, apidir +
"\http-response.adoc",
".http-response");
-
fileAppend(content, apidir +
"\response-fields.adoc",
".response-fields 返回值说明");
-
content.append(System.getProperty(
"line.separator"));
-
}
-
// System.out.println(adocPath);
-
// System.out.println(content);
-
File file =
new File(adocPath);
-
writeStringToFile(file, content.toString(),
"UTF-8");
-
}
-
-
private void writeStringToFile(File file, String content, String character) throws IOException {
-
if (!file.exists()) {
-
file.createNewFile();
-
}
-
FileOutputStream fos =
new FileOutputStream(file);
-
OutputStreamWriter osw =
new OutputStreamWriter(fos, character);
-
osw.write(content);
-
osw.flush();
-
}
-
-
private void fileAppend(StringBuilder content, String include, String title) {
-
File file =
new File(include);
-
if (file.exists()) {
-
content.append(title).append(System.getProperty(
"line.separator"));
-
content.append(
"include::").append(include).append(
"[]").append(System.getProperty(
"line.separator"));
-
}
-
}
对啦，告诉你们我是怎么知道加那个目录的，当然是看asciidoctor的语法文档啦,在这里：点击打开链接
嗯，项目源码在此：拿去参考吧，直接就能运行：点击打开链接
7721
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
