springboot~mockMvc和asciidoctor生成基於TDD的API文檔

API文檔是前端與後端快速開發，減小溝通成本的必要條件，有一份完善的文檔是很必要的，由經過測試來生成文檔的好處就是:測試數據有了，測試返回結果有了，並且能夠對這些字段進行說明，很清晰，在springboot框架裏，去使用mockMvc文檔生成時，須要有如下幾個步驟，大叔總結了一下，分享給你們。

一 mockMvc包引用

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

asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor'

二 snippetsDir插件引用

在buildscript塊裏添加以下代碼

maven {
    url "https://plugins.gradle.org/m2/"
}
mavenCentral()
dependencies {
    classpath "org.asciidoctor:asciidoctor-gradle-jvm:2.0.0-rc.1"

}

 添加插件

apply plugin: "org.asciidoctor.convert"

三 配置三大路徑的地址，三大路徑指，asciidoctor文檔路徑，生成的API文檔目錄和snippets目錄

jar { dependsOn asciidoctor from ("${asciidoctor.outputDir}/html5") { into 'static/docs' } } ext { snippetsDir = file('build/generated-snippets') } integTest { outputs.dir snippetsDir } asciidoctor {
 inputs.dir snippetsDir outputDir "build/asciidoc" dependsOn integTest 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.operation.preprocess.Preprocessors.prettyPrint; 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.Before; import org.junit.Rule; import org.junit.Test; import org.junit.runner.RunWith; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.restdocs.JUnitRestDocumentation; import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation; 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 org.springframework.test.web.servlet.setup.MockMvcBuilders; import org.springframework.web.context.WebApplicationContext; import test.lind.javaLindDay.controller.DocController; @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) @ActiveProfiles("integTest")//指定profile環境
@RunWith(SpringRunner.class) 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("購買者") ); @Rule public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(); protected MockMvc mockMvc; @Autowired private WebApplicationContext context; @Before public void setUp() { this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context) .apply(MockMvcRestDocumentation.documentationConfiguration(restDocumentation) .uris().withScheme("http").withHost("localhost").withPort(8080) .and() .operationPreprocessors().withResponseDefaults(prettyPrint())) .build(); } @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)); } @Test public void get_list() throws Exception { this.mockMvc.perform( get(DocController.DOC_LIST)) .andDo(print()) .andExpect(status().isOk()) .andDo(document("doc-list", orderResponseFieldsParameters)); } }

這裏有個須要注意的地址，get靜態方法的包應該是import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;不然會有找不到路由的

錯誤，這點困擾了我好久。

六 編譯，打包，它會同時去下載API DOC所須要的文件

gradle build

最後，進入build/asciidoc/html5目錄，瀏覽咱們的API說明文件便可。

  

感謝各位的閱讀！