这篇文章将带你了解如何用spring官方推荐的restdoc去生成api文档。本文创建一个简单的springboot工程,将http接口通过API文档暴露出来。只需要通过JUnit单元测试和Spring的MockMVC就可以生成文档。
创建工程 导入依赖
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
创建Controller 测试接口
@RestController
@RequestMapping("/test")
public class TestController {
@RequestMapping("/sayHello")
public String test(){
return "Hello World";
}
}
启动工程,访问http://localhost:8080/test/sayHello,浏览器显示:
Hello World
通过单元测试生成REST API文档
restdocs是通过单元测试生存snippets文件,然后snippets根据插件生成htm文档的。建一个单元测试类:
package com.bo.springboot;
import com.bo.springboot.controller.TestController;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import javax.annotation.Resource;
import static org.hamcrest.Matchers.containsString;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@RunWith(SpringRunner.class)
@WebMvcTest(TestController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class RestDocTest {
@Resource
private MockMvc mockMvc;
@Test
public void test01() throws Exception {
this.mockMvc.perform(get("/test/sayHello")).andDo(print()).andExpect(status().isOk())
.andExpect(content().string(containsString("Hello World")))
.andDo(document("test"));
}
}
其中,@ AutoConfigureRestDocs注解开启了生成snippets文件,并指定了存放位置。启动单元测试,测试通过,你会发现在target文件下生成了一个snippets文件夹,其目录结构如下:
└── target
└── snippets
└── test
└── curl-request.adoc
└── http-request.adoc
└── http-response.adoc
└── httpie-request.adoc
└── request-body.adoc
└── response-body.adoc
默认情况下,snippets是Asciidoctor格式的文件,包括request和reponse,另外其他两种httpie和curl两种流行的命令行的http请求模式。到目前为止,只生成了Snippets文件,接下来需要用Snippets文件生成文档。
使用用Snippets生成REST文档
创建一个新文件src/main/asciidoc/test.adoc 这个*.adoc路径应该是固定的,文件名称可自定义,*.adoc的书写格式,参考:http://docs.spring.io/spring-restdocs/docs/current/reference/html5/,这里不多讲解。
== 用 Spring REST Docs 构建API文档
This is an example output for a service running at http://localhost:8080
.request
include::{snippets}/test/http-request.adoc[]
.response
include::{snippets}/test/http-response.adoc[]
这个例子非常简单,通过单元测试和一些简单的配置就能够得到api文档了
需要在pom文件加上asciidoctor-maven-plugin插件:
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<executions>
<execution>
<id>generate-docs</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceDocumentName>test.adoc</sourceDocumentName>
<backend>html</backend>
<attributes>
<snippets>${project.build.directory}/snippets</snippets>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
注意:配置项的sourceDocumentName需要与上一步中新建的*.adoc文档名称一致。这时执行mvn package命令打包后就可以在/target/generated-docs下得到一个test.html文档了,打开文档界面如下:
参考资料
Creating API Documentation with Restdocs
https://docs.spring.io/spring-restdocs/docs/current/reference/html5/