发布/记录 Spring-REST API
我在 stackoverflow 和 google 上浏览了一下，但找不到任何可以记录 SPRING-REST api 的好工具。尝试使用 enunciate，但它因无法识别的 spring 注释而崩溃。有谁知道有一个用于记录 spring RESTful api 的好工具吗？
I have looked around a bit on stackoverflow as well as google, but couldn't find any good tool that can document SPRING-REST api. Tried using enunciate, but it barfed out on spring annotations it couldn't recognize. Does anyone know of a good tool for documenting a spring RESTful api ?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
通常，您不需要记录 REST API。应向您的客户提供您正在使用的媒体类型的规范（例如 Atom 或 OpenSearch），并且仅依赖那里提供的信息。
一旦您记录了有关特定服务的任何内容，您就将您的客户与该文档（以及该服务）联系起来。结果是，您的服务的发展能力现在受到客户端在其代码中烘焙的带外信息量的限制（基于您的 API 描述）。
IOW - 您最后一次需要服务 API 描述以使您的 feed 阅读器与 AtomPub 服务对话是什么时候？
简
P.S.我在[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
Typically you need not document your REST API. Your clients should be provided with the specification of the media type you are using (think Atom or OpenSearch for example) and only rely on the information given there.
As soon as you document anything about a specific service, you are coupling your clients to that documentation (and that service). The result being that your service's ability to evolve is now limited by the amount of out-of-band information the clients have baked in their code (based on your API description).
IOW - when was the last time you needed a service API description to make your feed reader talk to an AtomPub service?
Jan
P.S. The theoretical backgrounds I summarized in [1]. Look specifically at the difference between HTTP Type I/II and REST. And Roy's [2] is a MustRead on this.
[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
只需从客户端开发人员的角度记录需要记录的所有内容即可。并且请不要认真对待诸如“您不需要记录您的 REST API”之类的建议。这是一种迂腐的指导，在现实世界中没有用。
从客户端开发人员的角度来看，每一个成功的 API 都有详细的记录。任何拘泥于迂腐观念的 API 必然会让客户端开发人员望而却步。
有关一些示例，请参阅我的“RESTful Web Services Cookbook”(http://shop.oreilly.com/product/9780596801694.do) 的第 14 章。
Just document everything that needs to be documented from a client developer perspective. And please don't take advice like "you need not document your REST API" seriously. This is a pedantic guidance and not useful in the real world.
Every successful API out there is well documented from client developer point of view. Any API that is hung up on pedantic notions is bound to turn off client developers.
See Chapter 14 of my "RESTful Web Services Cookbook" (http://shop.oreilly.com/product/9780596801694.do) for some examples.
尝试使用 Swagger。它提供了一些自己的注释，可以与 Spring MVC 其余注释很好地配合。
Try using Swagger. It provides few of its own annotation that work well with Spring MVC rest annotations.