Spring REST Docs 帮助你管理 RESTful 服务文档，使用 Asciidoctor 来编写文档，使用 Spring MVC Test 自动生成片段。

首先什么样的风格叫做rest风格呢？

编程界的大家应该都有听说过restful风格能够提高项目的性能，而且现在到处都在说我们的项目是rest风格的，那么什么是rest风格呢？简单来举个例子 大家就能懂啦： 比如说现在有这样一个url： https://www.oschina.net/news/66853/spring-rest-docs-1-0-0 这里的66853可能是一个专用的id或者其他相关的映射，我们从这里是不能知道它到底指的是什么。 而如果是非restful风格的url则会是这样： https://www.oschina.net/news/uid?userUid=66853/spring-rest-docs-1-0-0 XXX?XXX= XXX这样大家都能猜出来的url，后来加密之后发送到后台，然后就出现了所谓的rest比较流行。

---

如何使用spring rest doc 生成api文档？

例子：SpringBoot工程，将http接口通过API文档暴露出来，只需要通过JUnit单元测试和spring的MockMVC就可以生成文档。 SpringRestDoc框架通过测试来生成REST接口的说明文档：可以对参数和返回值进行简单的说明，还能产生url和返回用例，通过单元测试，和目前的moxkMVC框架相结合，可以产生Asciidoctor文档片段。 缺点：目前只能生成片段，继承一整个API文档的话还需要手动去写。当然测试的越多，文档的内容就越详细。 解决方案：这里的只能产生片段文章，不能自动整合成一整个文档的缺点，可以使用我上一篇介绍的swagger去解决。swagger具有较强的能力和自信能做好这件事情 ，你就放心交给它好了。

基础配置

软件：idea jdk：1.8 maven：3.0+

---

简单粗暴，咱直接从操作开始哈：

1.在pom.xml文件中引入对应的maven依赖

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

2.再测试类中添加设置：

restdoc是通过单元测试生成snippets文件，然后snippets根据插件生成html文档 在测试类中的设置： (1)

public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");

(2) Then 在@before方法中配置MockMVC或者REST assured：

Setting up your JUnit tests

private MockMvc mockMvc; @Autowired private WebApplicationContext context; @Before public void setUp() { this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context) .apply(documentationConfiguration(this.restDocumentation)) .build(); }

MockMvc实例是使用一个配置MockMvcRestDocumentationConfigurer来配置的。这个类的一个实例可以是从org.springframework.restdocs.mockmvc.MockMvcRestDocumentation中的静态documentationConfiguration()方法获得。

Setting up your tests without JUnit 与上面不同的是不需要@Rule，并且换成了JUnitRestDocumentation

private ManualRestDocumentation restDocumentation = new ManualRestDocumentation("target/generated-snippets");

同样的，setup()方法中MockMVC的设置将变成这样：

private MockMvc mockMvc; @Autowired private WebApplicationContext context; @BeforeMethod public void setUp(Method method) { this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context) .apply(documentationConfiguration(this.restDocumentation)) .build(); this.restDocumentation.beforeTest(getClass(), method.getName()); }

但是在每个测试之后ManualRestDocumentation.afterTest()方法都将被调用一次：

@AfterMethod public void tearDown() { this.restDocumentation.afterTest(); }

3.Invoking the RESTful service

the testing framework被配置好之后，它就可以尝试去集成RESTful服务了，针对其中的请求和回复进行相应详细的说明。 举个栗子：(kotlin

@Resource private lateinit var context: WebApplicationContext private lateinit var mockMvc: MockMvc //设置测试片段生成文件夹的位置 @Rule @JvmField var restDocumentation = JUnitRestDocumentation("target/asciidoc/snippets") @Before fun setUp() { this.mockMvc = MockMvcBuilders.webAppContextSetup(context) .apply<DefaultMockMvcBuilder>(documentationConfiguration(this.restDocumentation)) .build() } @Test fun create() { val parentId = "sssssssssss" val request = post("/groups/$parent") this.mockMvc.perform(request) .andException(status.isCreated) .andDo(print()) .andDo(document("{methodName}", preprocessRequest(prettyPrint()))) }

举个Spring REST Docs的官方文档中的例子：（java） 我们可以在andDo()中添加一些对参数的具体描述：

this.mockMvc.perform(get("/locations/{latitude}/{longitude}", 51.5072,0.1275)) .andExpect(status().isOk()) .andDo(document("locations", pathParameters(parameterWithName("latitude").description("The location's latitude"),parameterWithName("longitude").description("The location's longitude") )));

关于这些Spring REST Docs的官方文档中对参数的具体描述的一些用法我就不详细赘述了，因为这个很显然，代码上看起来不整齐，此时也已经有更好的东西代替它了，所以我们直接学习更好的解决“为属性和回复消息进行详细说明”的问题的解决方案就好啦~

以上是在SpringRESTDocs的官方文档中学习到的知识，做以简单的总结。

---

【那么有什么好的解决方案呢？】 就是我上一篇文章提到的springfox-swagger，它是一个能力的强者，为什么呢？话不多说，举个简单的栗子： 使用springfox-swagger这个框架的时候，我们是把api的详细注释都添加在Controller层的各个类中： （kotlin）当然啦，想使用下面这段代码的模式，就需要配置集成springfox-swagger在你的项目中。（SpringBoot+SpringDataJPA+SpringFramework+Springfox-swagger）

@RestController @Api(value = "User", description = "the chapter of user") @RequestMapping("/users", produces = arrayOf(MediaType.APPLICATION_JSON_UTF8_VALUE)) class ItemController { @ApiOperation(value = "createUser", notes = "创建一个user") @ApiImplicitParams( ApiImplicitParam(name = "Name", value = "用户名", paramType = "path", required = true, dataType = "String"), ApiImplicitParam(name = "age", value = "用户的年龄", paramType = "path", required = true, dataType = "Int") ) @ApiResponses( ApiResponse(code = 200, message = "创建成功", response = User::class), ApiResponse(code = 404, message = "没有找到", response = Void::class) ) @PostMapping("{name}/age/{age}", consumes = arrayOf(MediaType.APPLICATION_JSON_UTF8_VALUE)) fun create(@PathVariable("name") userName: String, @PathVariable("age") userAge: Int): ResponseEntity<Any> { //此处实现的代码省略 //...... return user } }

关于Api的一些简单的注解，都在上一篇中有描述。

---

总结： （1）springRESTDocs主要是用来在测试的时候生成测试代码片段，并且在测试片段中添加一些简单的说明； （2）swagger主要是用来提供测试界面，并整合生成API接口文档； （3）MockMVC是一个属于spring MVC的测试框架，基于Restful风格的SpringMVC的测试，可以测试完成的流程。关于MockMVC的相关信息可以查看网址：http://www.cnblogs.com/lyy-2016/p/6122144.html他写的很棒，也可以看我之前写的博客。

代码举例：

下面 举一个完整的例子，结合springBoot+SpringDataJPA+SpringMVC+MockMVC+SpringRESTDocs+Springfox-swagger，完成生成一个具体的详细的API接口文档。

第一步：在Maven中配置Swagger2+SpringRESTDocs的jar包的依赖

mavne会自动下载你所需要的jar包

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>org.springframework.restdocs</groupId> <artifactId>spring-restdocs-mockmvc</artifactId> <version>1.1.2.RELEASE</version> <scope>test</scope> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-staticdocs</artifactId> <version>2.6.1</version> </dependency>

第二步：配置Swagger2

import org.springframework.context.annotation.Bean import org.springframework.context.annotation.Configuration import org.springframework.http.ResponseEntity import springfox.documentation.builders.ApiInfoBuilder import springfox.documentation.builders.PathSelectors import springfox.documentation.builders.RequestHandlerSelectors import springfox.documentation.service.ApiInfo import springfox.documentation.service.Contact import springfox.documentation.spi.DocumentationType import springfox.documentation.spring.web.plugins.Docket import springfox.documentation.swagger.web.UiConfiguration import springfox.documentation.swagger2.annotations.EnableSwagger2 @Configuration @EnableSwagger2 class Swagger2Config { @Bean fun restfulApi(): Docket { return Docket(DocumentationType.SWAGGER_2) .genericModelSubstitutes(ResponseEntity::class.java) .useDefaultResponseMessages(true) .forCodeGeneration(true) .select() .apis(RequestHandlerSelectors .basePackage("{你扫描API注解的包}")) .paths(PathSelectors.any()) .build() .pathMapping("/") .apiInfo(apiInfo()) } private fun apiInfo(): ApiInfo { return ApiInfoBuilder() .title("API文档") .description(this.description) .termsOfServiceUrl("http://terms.XXX.com") .contact(Contact("联系方式")) .version("1.0.0") .build() }

这里的@Configuration注解，让spring加载配置，@EnableSwagger2启用Swagger2 再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

第三步：设置swagger整合片段生成api的一些规范

import io.github.robwin.markup.builder.MarkupLanguage import io.github.robwin.swagger2markup.GroupBy import io.github.robwin.swagger2markup.Swagger2MarkupConverter import org.junit.Before import org.junit.Test import org.junit.runner.RunWith import org.springframework.boot.test.context.SpringBootTest import org.springframework.http.MediaType import org.springframework.test.context.junit4.SpringJUnit4ClassRunner import org.springframework.test.web.servlet.MockMvc import org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get import org.springframework.test.web.servlet.result.MockMvcResultMatchers.status import org.springframework.test.web.servlet.setup.MockMvcBuilders import org.springframework.web.context.WebApplicationContext import springfox.documentation.staticdocs.Swagger2MarkupResultHandler.outputDirectory import springfox.documentation.staticdocs.SwaggerResultHandler import javax.annotation.Resource @Test @Throws(Exception::class) fun convertToAsciiDoc() { // 得到swagger.json,写入outputDir目录中 this.mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON)) .andDo(SwaggerResultHandler.outputDirectory(outputDir).build()) .andExpect(status().isOk) .andReturn() // 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir // 这个outputDir必须和插件里面<generated></generated>标签配置一致 Swagger2MarkupConverter.from(outputDir + "/swagger.json") .withPathsGroupedBy(GroupBy.XXX)// 按XXX排序 .withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式 .withExamples(snippetDir) .build() .intoFolder(outputDir) // 输出 }

在单元测试的时候，SpringRestDocs会生成一些代码片段，这里就是将片段整合先生成一个json文件，再转换格式的过程。

第四步：在测试类中添加SpringRestDocs和Mockmvc的一些代码，进行单元测试

@Resource private lateinit var context: WebApplicationContext private lateinit var mockMvc: MockMvc @Rule @JvmField var restDocumentation = JUnitRestDocumentation("{SpringRestDocs生成测试片段的文件的绝对路径}") @Before fun setUp() { this.mockMvc = MockMvcBuilders.webAppContextSetup(context) .apply<DefaultMockMvcBuilder>(documentationConfiguration(this.restDocumentation)) .build() }

其中.apply(documentationConfiguration(this.restDocumentation))就是将MockMVC和SpringRestDocs结合在一起。 @Rule 表示当前是在Junit测试环境下的测试

@Test fun create() { val json = """ { "userName" : "userName", "age" : "24" } """ val request = post("/users") .contentType("{生产类型}") .content(json) .accept("{消费类型}") this.mockMvc.perform(request) .andExpect(status().isCreated) .andDo(print()) .andDo(document("createUser", preprocessResponse(prettyPrint()))) }

这里的andDo()之类的用法 ，我在之前的文章中都有讲过。这些都是用来模拟一个Mockmvc的请求。 这里的.andDo(document(“createUser”, preprocessResponse(prettyPrint())))是属于SpringRestDocs在生成的测试代码片段中加的一些简单的注释

第五步：在你设置的swagger2扫描的包下，填写api的注解，完善生成api文档中对属性和回复消息的内容。这里的扫描路径一般情况下都是SpringMVC中的Controller层

@ApiOperation(value = "createUser", notes = "创建一个user") @ApiImplicitParams( ApiImplicitParam(name = "Name", value = "用户名", paramType = "path", required = true, dataType = "String"), ApiImplicitParam(name = "age", value = "用户的年龄", paramType = "path", required = true, dataType = "Int") ) @ApiResponses( ApiResponse(code = 200, message = "创建成功", response = User::class), ApiResponse(code = 404, message = "没有找到", response = Void::class) ) @PostMapping("{name}/age/{age}", consumes = arrayOf(MediaType.APPLICATION_JSON_UTF8_VALUE)) fun create(@PathVariable("name") userName: String, @PathVariable("age") userAge: Int): ResponseEntity<Any> { //照例 ，中间实现的一些代码省略 return User }

这里所有的api注解，在单元测试完成之后，运行Swagger2的test，都能被整合到api接口文档中。其他的就不再赘述了。

---

over啦~ 待完善revision