我正在为新的内部Web服务编写RESTful API规范。它不是很长，也不是很简单，但是即使如此，这也是我第一次使用严格的REST（而不是出于实际原因作弊-避免这样做，PUT并且DELETE因为它们在PHP中很痛苦，依此类推）。我想知道是否有任何标准方法或最佳实践来记录REST接口？我希望团队中的其他成员能够一目了然地理解它，对于希望编写客户端的任何人，也可以在不了解底层代码的情况下做到这一点。
Answers:
当然，理想的REST API应该使用HATEOAS并由超文本驱动（大量使用媒体类型），但是对于开发人员来说，使用简单的人性化文档也很有帮助。
一些有助于生成文档的特定工具，例如：
在罗伊的帖子在这里，他指出
REST API应该花费几乎所有的描述性精力来定义用于表示资源和驱动应用程序状态的媒体类型，或者为现有标准媒体类型定义扩展的关系名称和/或启用超文本的标记。花费所有精力描述应该在媒体类型的处理规则范围内（并且在大多数情况下已由现有媒体类型定义）完全定义要在感兴趣的URI上使用的方法。
好的ReST文档将意味着仅记录您的媒体类型，而仅记录您的媒体类型。
在典型的情况下，您将生成如下文档：
可以通过在书签URI（通常是服务器的根目录http://www.acme.org）上向服务器发出GET或HEAD请求来找到文档中描述的各种资源链接。 HTTP链接标头：
Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml
其中rel部分是链接关系，而则xxx是已建立关系的URI。
本文档定义以下关系名称：
该application/vnd.acme.services+xml文档带有xml序列化，描述了应用程序可能要处理的链接列表。
<links>
<link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>
该applcation/vnd.acme.customers+xml是一个文档xml描述客户系列化。
<customers>
<customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>
等等...
重点是为开发人员提供一种方法来遵循您定义的链接。首先找到指向索引的链接，以便他们可以获得可以导航到的内容的列表。
一旦发现该文档，便发现他们可以看到某个Uri上的客户列表，并且可以GET对它进行处理。
如果他们找到感兴趣的客户，他们可以按照定义的链接/customers/customer/@href，并出具GET检索客户的表示。
从那里，您的媒体类型可以使用更多链接嵌入用户可用的操作。您还可以选择在资源上发出OPTIONS请求，以了解是否可以删除资源，或者在修改后可以将文档保存回PUT。
因此，从来没有好的文档：
所有这些的目的是实现客户端和服务器之间的最小耦合。客户端可以非常聪明地显示和发现资源（显示表单，上帝知道其他什么），但是对于实际的工作流程却完全是愚蠢的：服务器决定。
在我公司，使用Web应用程序描述语言WADL非常高兴。Wikipedia将其描述为：“一种基于XML的文件格式，提供了基于HTTP的Web应用程序的机器可读描述”。我发现原始的WADL易于编写，阅读和理解，并且直接映射到RESTful概念。官方项目提供了一个简单的规范，XSD和RELAX NG模式以及Java工具。
存在许多使用WADL的工具和资源，包括：
提示：尝试doc使用XHTML命名空间将HTML元素包括在内，从而在WADL文档的元素中包含易于理解的文档，例如描述，概念，入门，使用技巧等。可以有很大的不同！
要创建理解/文档，并非总是需要重量级的解决方案。重量级工具的示例包括：IO /文档/ Apigee（尽管功能强大）。
对于已经具有docchain设置的小型项目（doxygen / phpdoc / phpdoctor / custom / etc），我使用以下shellscript将页面包含在完整的生成文档中：
https://gist.github.com/4496972
它只在源代码中使用自定义注释标签。对于记录任何源代码（语言），这也是一个不错的起点。