发布/记录Spring-REST API

Question

我已经在stackoverflow以及google上查了一下，但是找不到任何可以记录SPRING-REST api的好工具。尝试使用enunciate，但它在春天注释中被禁止它无法识别。有没有人知道用于记录spring RESTful api的好工具？

Answer 1

通常，您无需记录REST API。应向您的客户提供您正在使用的媒体类型的规范（例如Atom或OpenSearch），并且只依赖于那里提供的信息。

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

IOW - 您最后一次需要服务API说明以使您的Feed阅读器与AtomPub服务通信时是什么时候？

扬

P.S。我在[1]中总结的理论背景。请特别注意HTTP Type I / II和REST之间的区别。而Roy的[2]就是MustRead。

[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 2

从客户端开发人员的角度记录需要记录的所有内容。请不要认真对待“你不需要记录你的REST API”这样的建议。这是一个迂腐的指导，在现实世界中没用。

从客户端开发人员的角度来看，每个成功的API都有详细记录。任何挂在迂腐观念上的API都必然会关闭客户端开发人员。

有关示例，请参阅我的“RESTful Web Services Cookbook”（http://shop.oreilly.com/product/9780596801694.do）的第14章。

Answer 3

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