您如何记录 REST API？不仅是关于资源是什么的文档，而且实际上是在请求中发送的数据是什么，以及在响应中发回的数据是什么。知道某些东西期望发送 XML 并返回 XML 是不够用的；或 JASN；管他呢。您如何记录在请求中发送的数据和在响应中发回的数据？
到目前为止，我能找到的最好的工具是 Enunciate 工具，您可以在其中记录您的 REST API 和数据元素。 Enunciate 是否适合此类型的工具，我是否错过了任何其他提供此功能的工具，我应该看看？
我的 REST API 的使用者可以使用任何语言 python、Java、.NET 等
【问题讨论】：
我为我的项目决定的方法是 Enunciate。似乎是 REST API 文档的事实标准。
【讨论】：
我可能错了，但您似乎想要类似于 WSDL 和 XML Schema 的东西来记录您的 API。我建议阅读 Joe Gregorio 在Do we need WADL 上的帖子？它很好地讨论了为什么不将这种方法用于 REST API。如果您不想阅读整篇文章，其基本思想是类似 API 的文档（即 WADL）永远不够用，并且会导致接口脆弱。另一篇好文章是Does REST need a description language?它有很多很好的链接到这种类型的讨论。
虽然他的帖子为您提供了不该做什么的建议，但并没有真正回答您应该做什么的问题。 REST 的重要之处在于统一接口的想法。换句话说，GET、PUT、POST 和 DELETE 应该完全按照您的想法去做。 GET 检索资源的表示、PUT 更新、POST 创建和 DELETE 删除。
接下来的大问题是关于描述您的数据及其含义。您始终可以采用定义 XML Schema 或类似方法的方法，并从该模式生成文档。就个人而言，我发现机器生成的文档并不是那么有用。
以我的拙见，最好的数据格式具有广泛的、人类可读的文档和示例。这是我知道如何正确描述语义的唯一方法。我喜欢使用Sphinx 来生成这种类型的文档。
【讨论】：
我不确定您是在寻求一种工具来帮助您，还是在询问最佳实践是什么（或两者兼而有之）。
就最佳实践而言，与其他软件文档一样适用于 REST 文档 - 提供具有广度的良好登录页面（即，按逻辑组织的资源列表，其中包含关于它们的功能及其 URI 的简介）下钻页面，通过示例深入解释每个页面的功能。 Twitter 的 REST API 有很好的文档记录，应该是一个很好的模型。
Sample drilldown of one resource
我真的很喜欢那个向下钻取页面。它列出了您需要的所有参数，以及每个参数的说明。它有一个侧边栏，列出了支持的类型。它具有指向相关页面和具有相同标签的其他页面的链接。它有一个示例请求和响应。
【讨论】：