使用spring rest docs 进行单元测试

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.bootgroupId>
      <artifactId>spring-boot-starter-webartifactId>
    dependency>

    <dependency>
      <groupId>org.springframework.bootgroupId>
      <artifactId>spring-boot-starter-testartifactId>
      <scope>testscope>
    dependency>

    <dependency>
      <groupId>org.springframework.restdocsgroupId>
      <artifactId>spring-restdocs-mockmvcartifactId>
      <scope>testscope>
    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(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 {
        //此处实现的代码省略
        //......
        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包

        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.6.1version>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.6.1version>
        dependency>
        <dependency>
            <groupId>org.springframework.restdocsgroupId>
            <artifactId>spring-restdocs-mockmvcartifactId>
            <version>1.1.2.RELEASEversion>
            <scope>testscope>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-staticdocsartifactId>
            <version>2.6.1version>
        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必须和插件里面标签配置一致
        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(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