利用spring-restdocs-mockmvc生成API文件

1.專案pom引入依賴的jar包：

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

2.springboot構建啟動專案，編寫Controller控制器

3.編寫單元測試用例

@RunWith(SpringRunner.class)
@WebMvcTest(MockController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
//@SpringBootTest  //這個不能跟WebMvcTest同時存在，只能選擇一個，建立API文件採用WebMvcTest
public class MockmvcApplicationTests {

   @Autowired
MockMvc mockMvc ;
@Test
public void contextLoads() throws 
 
Exception {

      String name ="7" ;
      this.mockMvc.perform(get("/").param("name",name)).andDo(print()).andExpect(status().isOk())
            .andExpect(content().string(containsString("hello "+name)))
            .andDo(document("home"));
}

}

@ AutoConfigureRestDocs註解開啟了生成snippets檔案，並指定了存放位置

4.利用snippets檔案生成adoc檔案，pom中引入plugin外掛

<build>
   <plugins>
      <plugin>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-maven-plugin</artifactId>
         <configuration>
            <executable>true</executable>
         </configuration>
      </plugin>
      <plugin>
         <groupId>org.asciidoctor</groupId>
         <artifactId>asciidoctor-maven-plugin</artifactId>
         <version>1.5.2</version>
         <executions>
            <execution>
               <id>generate-docs</id>
               <phase>prepare-package</phase>
               <goals>
                  <goal>process-asciidoc</goal>
               </goals>
               <configuration>
                  <sourceDocumentName>index.adoc</sourceDocumentName>
                  <backend>html</backend>
                  <doctype>book</doctype>
                  <attributes>
                     <snippets>${project.build.directory}/snippets</snippets>
                  </attributes>
               </configuration>
            </execution>
         </executions>
      </plugin>
   </plugins>
</build>

這樣會在編譯目錄下的generate-docs生成html檔案

5.利用AsciidocFX工具，可以引入html檔案等進行整合，生成更加標準直觀的API文件

6.demo程式碼git中mockmvc

一個應用controller測試例項：

package com.lexue.english.child.test.integration;


import static org.hamcrest.CoreMatchers.notNullValue;
import static org.hamcrest.Matchers.is;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;


import org.junit.Before;
import org.junit.FixMethodOrder;
import org.junit.Rule;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.junit.runners.MethodSorters;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.restdocs.JUnitRestDocumentation;
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 com.fasterxml.jackson.databind.ObjectMapper;
import com.lexue.english.child.domain.mongodb.ProgressEntity;
import com.lexue.english.child.protocol.common.Request;
import com.lexue.english.child.protocol.type.RetCode;
import com.lexue.english.child.repository.mongodb.ProgressRepository;


import lombok.extern.slf4j.Slf4j;


@RunWith(SpringRunner.class)
@SpringBootTest
@Slf4j
@FixMethodOrder(MethodSorters.NAME_ASCENDING)
public class AchievementControllerTests {

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

@Autowired
private ObjectMapper objectMapper;

@Autowired
private WebApplicationContext context;


private MockMvc mockMvc;
@Autowired
private ProgressRepository repository;



@Before
public void setUp() {
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
.apply(documentationConfiguration(this.restDocumentation))
.alwaysDo(document("{method-name}/{step}/"))
.build();
}

@Test
public void test0_findAchievement() throws Exception {


ProgressEntity progress = repository.findOne(888888L);
progress.setArchievement("archievement");
repository.save(progress);

Request<Object> request2 = new Request<>();
request2.setDeviceId("5555555");
request2.setSessionId("666666666");

log.debug(objectMapper.writeValueAsString(request2));

this.mockMvc.perform(
post("/ce/1.0/ac/info")
.accept(MediaType.APPLICATION_JSON)
.contentType(MediaType.APPLICATION_JSON)
.content(objectMapper.writeValueAsString(request2)))
.andExpect(status().isOk())
.andExpect(jsonPath("rc", is(RetCode.SUCCESS.ordinal())))
.andExpect(jsonPath("rep", is(notNullValue())))
.andExpect(jsonPath("rep.ac", is("archievement")))
.andDo(document("ac_info"));

}
}