发布/记录Spring-REST API

Question

我在stackoverflow和google上看了一下，但找不到任何可以记录SPRING-REST api的好工具。我试着使用了enunciate，但它在无法识别的spring注解上吐了出来。有没有人知道记录spring RESTful api的好工具？

Answer 1

通常，您不需要记录REST API。应该向您的客户端提供您正在使用的媒体类型的规范(例如，考虑Atom或OpenSearch )，并且只依赖于那里给出的信息。

一旦您记录了关于特定服务的任何内容，您就将客户耦合到该文档(和该服务)。其结果是，您的服务的发展能力现在受到客户端在其代码中烘焙的带外信息的数量的限制(基于您的API描述)。

IOW --您上一次需要服务应用程序接口描述来使您的提要阅读器与AtomPub服务对话是什么时候？

1月

附注:我在1中总结的理论背景。具体查看HTTP类型I/II和REST之间的差异。罗伊的2是这方面的MustRead。

1 2

Answer 2

只需从客户端开发人员的角度记录所有需要记录的内容即可。请不要把“你不需要记录你的REST API”之类的建议当真。这是一种学院派的指导，在现实世界中没有用处。

从客户端开发人员的角度来看，每个成功的API都有很好的文档记录。任何停留在书呆子概念上的API都必然会让客户端开发人员望而却步。

有关示例，请参阅我的"RESTful网络服务指南“(http://shop.oreilly.com/product/9780596801694.do)的第14章。

Answer 3

尝试使用Swagger。它提供了一些自己的批注，可以很好地与Spring MVC rest批注配合使用。