這篇文章將帶你了解如何用spring官方推薦的restdoc去生成api文檔。本文創建一個簡單的springboot工程，將http接口通過Api文檔暴露出來。只需要通過 JUnit單元測試和Spring的MockMVC就可以生成文檔。完整項目的源碼來源 技術支持一七九一七四三三八零
準備工作
你需要15min
Jdk 1.8
maven 3.0+
idea
創建工程
引入依賴，其pom文件：
通過@SpringBootApplication,開啟springboot
<dependencies><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></dependencies>
復制代碼通過@SpringBootApplication,開啟springboot
@SpringBootApplication
public class Application {public static void main(String[] args) {SpringApplication.run(Application.class, args);}
}
復制代碼在springboot通常創建一個controller:
@RestController
public class HomeController {``@GetMapping("/")public Map<String, Object> greeting() {return Collections.singletonMap("message", "Hello World");}}
復制代碼啟動工程，訪問localhost:8080，瀏覽器顯示：
{“message”:”Hello World”}
復制代碼證明接口已經寫好了，但是如何通過restdoc生存api文檔呢
Restdoc,通過單元測試生成api文檔 restdocs是通過單元測試生存snippets文件，然后snippets根據插件生成htm文檔的。
建一個單元測試類：
@RunWith(SpringRunner.class)
@WebMvcTest(HomeController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class WebLayerTest {@Autowiredprivate MockMvc mockMvc;@Testpublic void shouldReturnDefaultMessage() throws Exception {this.mockMvc.perform(get("/")).andDo(print()).andExpect(status().isOk()).andExpect(content().string(containsString("Hello World"))).andDo(document("home"));}
}
復制代碼其中，@ AutoConfigureRestDocs注解開啟了生成snippets文件，并指定了存放位置。
啟動單元測試，測試通過，你會發現在target文件下生成了一個snippets文件夾，其目錄結構如下：
└── target└── snippets└── home└── httpie-request.adoc└── curl-request.adoc└── http-request.adoc└── http-response.adoc
復制代碼默認情況下，snippets是Asciidoctor格式的文件，包括request和reponse，另外其他兩種httpie和curl兩種流行的命令行的http請求模式。 到目前為止，只生成了Snippets文件，需要用Snippets文件生成文檔。
