10

您如何记录 REST API？不仅是关于资源是什么的文档，而且实际上是在请求中发送的数据是什么，以及在响应中发回的数据是什么。知道某些东西期望发送 XML 并返回 XML 是不够用的；或 JASN；管他呢。您如何记录在请求中发送的数据以及在响应中发送回的数据？

到目前为止，我能找到的最好的是 Enunciate 工具，您可以在其中记录您的 REST API 和数据元素。Enunciate 是否适合此类型的工具，我是否错过了任何其他提供此功能的工具，我应该看看？

我的 REST API 的使用者可以使用任何语言 python、Java、.NET 等

4

4 回答 4

12

我为我的项目决定的方法是 Enunciate。似乎是 REST API 文档的事实标准。

于 2012-08-14T18:09:31.137 回答
6

我有使用 Enunciate 的经验，这很棒，但我不太喜欢你可以用它生成的客户端。另一方面，我在上一个项目中一直在使用swagger，它似乎符合我的需求，真的很酷，你应该试一试！

2016 年3 月 8 日更新：看起来您可以使用 Enunciate 来构建swagger文档。
看到这个。

于 2012-08-24T17:35:21.483 回答
2

我可能错了，但您似乎想要类似于 WSDL 和 XML Schema 的东西来记录您的 API。我建议阅读 Joe Gregorio 关于我们是否需要 WADL的帖子？它很好地讨论了为什么不将这种方法用于 REST API。如果您不想阅读整篇文章，其基本思想是类似 API 的文档（即 WADL）永远不够用，并且会导致接口脆弱。另一篇好文章是REST 需要描述语言吗？它有很多很好的链接到这种类型的讨论。

虽然他的帖子给了你不该做什么的建议，但它并没有真正回答你应该做什么的问题。REST 的重要之处在于统一接口的想法。换句话说，GET、PUT、POST 和 DELETE 应该完全按照您的想法去做。GET 检索资源的表示、PUT 更新、POST 创建和 DELETE 删除。

那么最大的问题是关于描述您的数据及其含义。您始终可以采用定义 XML Schema 或类似方法的方法，并从该模式生成文档。就个人而言，我发现机器生成的文档并不是那么有用。

以我的拙见，最好的数据格式具有广泛的、人类可读的文档和示例。这是我知道如何正确描述语义的唯一方法。我喜欢使用Sphinx来生成这种类型的文档。

于 2012-08-14T21:30:55.860 回答
0

我不确定您是否在寻求一种工具来帮助您，或者您是否在询问最佳实践是什么（或两者兼而有之）。

就最佳实践而言，与其他软件文档一样适用于 REST 文档 - 提供具有广度的良好登录页面（即，您的资源列表以逻辑方式组织，并带有关于它们所做的事情及其 URI 的简介）和向下钻取页面详细解释了每个页面的功能，并附有示例。Twitter 的 REST API 有很好的文档记录，应该是一个很好的模型。

Twitter API 主页

一种资源的示例钻取

我真的很喜欢那个向下钻取页面。它列出了您需要的所有参数，以及每个参数的说明。它有一个侧边栏，列出了支持的类型。它具有指向相关页面和具有相同标签的其他页面的链接。它有一个示例请求和响应。

于 2012-08-14T18:27:15.390 回答