Spring Rest文档生成

作者

本文版权归作者所有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。

转载自夜明的孤行灯

本文链接地址: https://www.huangyunkun.com/2018/03/31/spring-rest-docs/

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

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的模板和样式。

参考

https://projects.spring.io/spring-restdocs/

https://github.com/ScaCap/spring-auto-restdocs

https://www.slideshare.net/fbenz/introducing-spring-auto-rest-docs

本文版权归作者所有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。

转载自夜明的孤行灯

本文链接地址: https://www.huangyunkun.com/2018/03/31/spring-rest-docs/

发表评论