本文共 4786 字，大约阅读时间需要 15 分钟。

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

1.项目pom引入依赖的jar包：

      
    
     org.springframework.boot
       
    
     spring-boot-starter-web
    
   
      
    
     org.springframework.boot
       
    
     spring-boot-starter-test
       
    
     test
    
   
      
    
     org.springframework.restdocs
       
    
     spring-restdocs-mockmvc
       
    
     test
    
   

2.springboot构建启动项目，编写Controller控制器

3.编写单元测试用例

@RunWith(SpringRunner.class)@WebMvcTest(MockController.class)@AutoConfigureRestDocs(outputDir = "target/snippets")//@SpringBootTest  //这个不能跟WebMvcTest同时存在，只能选择一个，创建API文档采用WebMvcTestpublic 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插件

      
          
              
      
       org.springframework.boot
               
      
       spring-boot-maven-plugin
               
                  
       
        true
                
            
           
              
      
       org.asciidoctor
               
      
       asciidoctor-maven-plugin
               
      
       1.5.2
               
                  
                      
        
         generate-docs
                       
        
         prepare-package
                       
         
         
          process-asciidoc
          
                       
         
         
          index.adoc
          
         
          html
          
         
          book
          
          
          
           ${project.build.directory}/snippets
           
          
                    
                
            
        
    
   

注意adoc文档需要创建一个src-main-asciidoc文件夹下

这样会在编译目录下的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")); } }

参考地址：