springboot~mockMvc和asciidoctor生成基于TDD的API文档

API文档是前端与后端快速开发,减少沟通成本的必要条件,有一份完善的文档是很必要的,由通过测试来生成文档的好处就是:测试数据有了,测试返回结果有了,而且可以对这些字段进行说明,很清晰,在springboot框架里,去使用mockMvc文档生成时,需要有以下几个步骤,大叔总结了一下,分享给大家。

一 mockMvc包引用

testCompile('org.springframework.restdocs:spring-restdocs-mockmvc')

二 snippetsDir插件引用

plugins {
    id "org.asciidoctor.convert" version "1.5.3"
}

配置三大路径的地址,三大路径指,asciidoctor文档路径,生成的API文档目录和snippets目录

jar {
    group = 'test.lind'
    version = '0.0.1-SNAPSHOT'
    sourceCompatibility = 1.8
    dependsOn asciidoctor
    from ("${asciidoctor.outputDir}/html5") {
        into 'static/docs'
    }
}

ext {
    snippetsDir = file('build/generated-snippets')
}


integTest {
    outputs.dir snippetsDir
}


asciidoctor {
    attributes 'snippets': snippetsDir
    inputs.dir snippetsDir
    outputDir "build/asciidoc"
    dependsOn test
    sourceDir 'src/docs/asciidoc'
}

四 添加API接口

@RestController
public class DocController {
  public static final String DOC = "/doc/{name}";
  public static final String DOC_LIST = "/doc/list";

  @GetMapping(DOC)
  public Map<String, String> index(@PathVariable String name) {
    Map<String, String> maps = new HashMap<>();
    maps.put("name", "Hello");
    maps.put("sex", "1");
    maps.put("buyer", name);
    return maps;
  }
}

五 添加测试用例

package test.lind.javaLindDay;

import static org.hamcrest.Matchers.containsString;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.relaxedRequestFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.relaxedResponseFields;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
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;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.restdocs.payload.RequestFieldsSnippet;
import org.springframework.restdocs.payload.ResponseFieldsSnippet;
import org.springframework.restdocs.request.PathParametersSnippet;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import test.lind.javaLindDay.controller.DocController;

@ActiveProfiles("integTest")//指定profile环境
@RunWith(SpringRunner.class)
@WebMvcTest(DocController.class)
@AutoConfigureRestDocs(outputDir = "build/generated-snippets")
public class MockMvcTest {
  static final ResponseFieldsSnippet orderResponseFieldsParameters = relaxedResponseFields(
      fieldWithPath("name").description("账号"),
      fieldWithPath("buyer").description("购买者"),
      fieldWithPath("sex").description("性别")
  );
  static final RequestFieldsSnippet orderRequestFieldsParameters = relaxedRequestFields(
      fieldWithPath("code").description("凭证号"),
      fieldWithPath("word").description("凭证字"),
      fieldWithPath("batch").description("批次")
  );
  static final PathParametersSnippet orderRequestPathParameters = pathParameters(
      parameterWithName("name").description("购买者")
  );

  @Autowired
  private MockMvc mockMvc;

  @Test
  public void get_orders() throws Exception {
    this.mockMvc.perform(
        get(DocController.DOC, "zzl"))
        .andDo(print())
        .andExpect(status().isOk())
        .andExpect(content().string(containsString("Hello")))
        .andDo(document("doc-index", orderRequestPathParameters, orderResponseFieldsParameters));
  }

}

这里有个需要注意的地址,get静态方法的包应该是 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
否则会有找不到路由的

错误,这点困扰了我很久。

编译,打包,它会同时去下载API DOC所需要的文件

gradle build

最后,进入build/asciidoc/html5目录,浏览我们的API说明文件即可。

感谢各位的阅读!

原文 

http://www.cnblogs.com/lori/p/9184579.html

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。

PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » springboot~mockMvc和asciidoctor生成基于TDD的API文档

赞 (0)
分享到:更多 ()

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址