RESTful API文档
我将很快devise一个RESTful API，因此我需要描述它以使其他人能够开始使用它来实现客户端。
我查了一下，但不幸的是，我还没有发现任何描述基于Web的RESTful服务的标准化forms。 我要找的东西就像JavaDoc，尽pipe它不一定要用任何代码生成。 我也不是在谈论像WADL这样的东西，我宁愿要有一些我可以分发的人类可读文档。
由于RESTful基于Web的服务的性质，标准化文档应该相当容易。 它应该只列出可用的资源，相应的URI，允许的方法，内容types并描述可用的操作。 你有什么build议吗？
在此先感谢和问候
由于RESTful基于Web的服务的性质，标准化文档应该相当容易。 它应该只列出可用的资源，相应的URI，允许的方法，内容types并描述可用的操作。 你有什么build议吗？
这绝对是关于loggingREST服务的错误方法。
一个统治他们的URI
您不应该枚举资源的URI，因为这会鼓励客户端将这些URI硬编码到客户端代码中。 这会在客户端和服务器之间造成不必要的耦合。 应根据从服务根URI导航来发现URI。 根URI是唯一应该logging的URI。 文档应着重描述返回的表示中的信息和链接。 如果从以根URI返回的表示forms开始，则可以描述介质types以及该文档中可能提供的链接。
别名您的URI
使用某种别名在客户端和服务器之间创build一个间接层非常重要。 如果遵循atom：link标准来定义链接，那么rel属性将成为标识符。 然而，还有其他的方式来定义链接，例如，图像embedded在HTML中的方式。 一个图像标签可以有一个Id和一个href。 Id标签应该用来标识你想要访问URL的图像。
媒体types定义您的API
最终的结果是，您可以在某种表示的上下文中定义API中的所有端点。 完整的API由一组返回的表示和连接它们的链接定义。
所以你可能会问，有什么区别？ 为什么不创build端点列表？ 这是几个原因，
可更改的URI空间
由于这些链接是由客户端使用别名访问的，因此可以完全更改站点的整个URL结构，而不会影响客户端。 这使得所有的无穷无尽的“什么是构build我的分层url的最佳方式”几乎无关紧要。 你可以尝试一种方式，如果它不起作用，只要改变它，你不会破坏任何客户端代码或不得不改变任何文档！
dynamic分配
这不仅是您可以更改的URI的path部分。 你也可以改变主机。 想象一下，您的应用开始获得比预期更多的使用，您可以轻松地将所有图像或video资源的主机更改为指向不同的服务器。 你甚至可以通过返回不同的主机提供简单的负载平衡。 由于RESTful API是无状态的，因此哪个服务器响应请求确实无关紧要。 此function对于如此多的场景非常有用：将HTTPS内容移动到专用服务器上，根据客户端位置在地理上分配请求，将应用程序的function垂直划分到不同的服务器上。
显式协议
只是因为一个表示可能会返回一个链接，并不意味着它总是会的。 服务器只能根据当前资源状态返回允许的链接。 当与服务器资源进行交互时需要遵循特定的协议时，这可能非常有用。 客户端代码不需要了解协议的规则，它只能向用户呈现服务器可用的链接。
你不能自动化有趣的东西
为什么大多数自动化文档loggingREST服务的原因是无效的，因为统一的界面不需要logging简单的东西。 一旦理解了HTTP（请参阅RFC2616），就可以了解API的所有机制。 剩下的就是无法生成的真正有趣的域特定信息。
看好的一面，文件应该更短。 任何额外的可用时间应该用于提供如何在常见场景中导航API的示例。
没有标准，只是一个公开的辩论。 InfoQ有一篇有趣的文章： 描述RESTful应用程序 。
如果您使用类似JAX-RS的东西，您可以使用实际的JavaDoc作为参考。 或者做注释扫描并自动生成它也不应该太难，尽pipe我不知道具体的实现。
如果您使用的是MVC模式，则URL通常表示为：
example.com/class/function/ID
这些都是实用可访问的信息，这意味着您仍然可以使用JavaDoc并能够loggingRESTful方法，因为URL的每个部分都连接到源代码本身。
