RESTful应用编程接口文档

Question

我很快就会设计一个RESTful应用程序接口，因此我需要对它进行描述，以便其他人能够开始使用它来实现客户端。

我看了一下，但不幸的是，我还没有找到任何描述基于web的RESTful服务的标准化形式。我正在寻找的是类似JavaDoc的东西，尽管它不需要从任何类型的代码中生成。我也不是在谈论像WADL这样的东西，我更希望有一些可以分发的人类可读的文档。

由于RESTful基于web的服务的性质，标准化文档应该是相当容易的。它应该只列出可用的资源，对应的URI，允许的方法，内容类型，并描述可用的操作。因此，您有什么建议吗？

提前致谢&问候

Answer 1

由于RESTful基于web的服务的性质，标准化文档应该是相当容易的。它应该只列出可用的资源，对应的URI，允许的方法，内容类型，并描述可用的操作。因此，您有什么建议吗？

这绝对是记录REST服务的错误方式。

一个URI来管理它们

您永远不应该枚举资源的URI，因为这会鼓励客户端将这些URI硬编码到客户端代码中。这在客户端和服务器之间创建了不必要的耦合。应该基于从服务根URI导航来发现URI。根URI是唯一应该记录的URI。文档应该侧重于描述返回的表示中有哪些信息和链接。如果从根URI返回的表示开始，就可以描述媒体类型以及该文档中可能提供的链接。

为您的URI指定别名

使用某种别名在客户端和服务器之间创建一个间接层是很重要的。如果您遵循atom:link标准来定义链接，那么rel属性就成为标识符。然而，还有其他方式来定义链接，例如，图像嵌入到html中的方式。一个图像标签可以有一个Id和一个href。Id标签应用于标识您希望访问其URL的图像。

媒体类型定义您的API

最终结果是您在某个表示的上下文中定义了API中的所有端点。完整的API由一组返回的表示和连接它们的链接定义。

所以你可能会问，有什么不同？为什么不直接创建端点列表呢？这里有几个原因，

可变URI空间

由于这些链接是由客户端使用别名访问的，因此可以完全更改站点的整个URL结构，而不会影响客户端。这使得无休止的“什么是构建我的分层URL的最佳方式”的问题变得无关紧要。您可以尝试一种方法，如果它不起作用，只需更改它，您不会破坏任何客户端代码或必须更改任何文档！

动态分布

您可以更改的不仅仅是URI的路径部分。您还可以更改主机。想象一下，您的应用程序开始获得比您预期更多的使用，您可以轻松地更改所有图像或视频资源的主机以指向不同的服务器。您甚至可以通过返回不同的主机来提供简单的负载平衡。由于RESTful API是无状态的，因此由哪台服务器响应请求实际上并不重要。此功能适用于许多场景:将HTTPS内容移动到专用服务器上，根据客户端位置在地理上分发请求，将应用程序的功能垂直划分到不同的服务器上。

显式协议

仅仅因为一个表示可能返回一个链接，并不意味着它总是会返回。服务器只能返回基于当前资源状态允许的链接。当与服务器资源交互时需要遵循特定的协议时，这会非常有用。客户端代码不需要理解协议规则，它只需向用户显示服务器提供的链接即可。

你不能自动生成有趣的东西

记录REST服务的大多数自动化工作之所以无效，是因为统一接口消除了记录简单内容的需要。一旦你理解了超文本传输协议(参见RFC2616)，你就理解了它的所有机制。剩下的就是无法生成的真正有趣的领域特定信息。

往好的方面看，文档应该短得多。任何额外的可用时间都应该花在提供如何在常见场景中导航API的示例上。

Answer 2

没有标准，只有一个公开的辩论。在InfoQ上有一篇有趣的文章：Describing RESTful Applications。

Answer 3

如果你使用像JAX-RS这样的东西，你可以使用实现的实际JavaDoc作为参考。或者做注解扫描并自动生成它也不会太难，尽管我不知道具体的实现。