转载

Spring Rest文档生成

写文档这个事情绝对是软件开发中最纠结的时候了，大部分时候你首先考虑的项目交付，但是从长远来看，一份文档，可以减少很多问题。

Spring提供了一个Rest doc扩展，可以从单元测试中读取一些一些信息并生成文档。

@Before
public void setUp() {
 this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
 .apply(documentationConfiguration(this.restDocumentation)) 
 .build();
}

首先配置上需要应用文档生成器，这个是一行代码的时候，无所谓。

但是对于文档的内容，你其实需要从代码中注明，比如

this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
 .andExpect(status().isOk())
 .andDo(document("index",
 responseFields( 
 subsectionWithPath("contact")
 .description("The user's contact details"))));

andDo之后的和测试本身并无关联，只是为了文档生成。

这个方案在我看来无非就是把文档写到了代码中，并没有根据测试的期待输入和期待输出直接生成文档。

ScaCap的Auto-Restdocs项目是我目前找到的比较好的解决方案，它除了要求andDo之后表明文档名称以外不强制要求别的信息。

它会从请求的字段中，还有请求的POJO中抽取字段和验证信息，文档本身还是使用的Spring Rest Docs的模板和样式。

Spring Rest文档生成