发布/记录Spring-REST API

Question

我已经在stackoverflow和google上浏览了一下，但是找不到任何可以记录SPRING-REST api的好工具。 尝试使用enunciate，但是在无法识别的spring注释上倒转。 有谁知道一个很好的工具来记录spring RESTful api？

Answer 1

尝试使用Swagger。 它提供了一些自己的注释，这些注释无法与Spring MVC其余注释一起使用。

Answer 2

通常，您无需记录REST API。 应该为您的客户提供所用媒体类型的规范（例如Atom或OpenSearch），并且仅依赖那里提供的信息。

一旦您记录了有关特定服务的任何内容，就会将客户与该文档（和该服务）联系起来。 结果是您的服务的发展能力现在受到客户端在其代码中烘烤的带外信息量的限制（基于您的API描述）。

IOW-上一次您需要服务API描述来使Feed阅读器与AtomPub服务对话是什么时候？

一月

PS我在[1]中总结了理论背景。 专门研究HTTP Type I / II和REST之间的区别。 而罗伊（Roy）的书（2）对此必读。

[1] http://www.nordsc.com/ext/classification_of_http_based_apis.html [2] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-Hypertext-driven

Answer 3

只需从客户开发人员的角度记录所有需要记录的内容。 并且，请不要认真考虑“您无需记录REST API”之类的建议。 这是一种学问指导，在现实世界中没有用。

从客户端开发人员的角度来看，每个成功的API都有详尽的文档记录。 根植于学究观念的任何API都将关闭客户端开发人员。

有关某些示例，请参见我的“ RESTful Web服务指南”（http://shop.oreilly.com/product/9780596801694.do）的第14章。