您如何记录REST API？

Question

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

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

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

Answer 1

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

Answer 2

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

更新03/08/2016：您似乎可以使用Enunciate构建 swagger 文档。
请参阅this。

Answer 3

我可能错了，但似乎你想要类似于WSDL和XML Schema的东西来记录你的API。我建议在Do we need WADL上阅读Joe Gregorio的帖子？它讨论了为什么不将此方法用于REST API。如果您不想阅读整篇文章，基本思想是类似API的文档（即WADL）将永远不够，并将导致脆弱的接口。另一篇好文章是Does REST need a description language？它与这种类型的讨论有很多很好的联系。

虽然他的帖子为你提供了什么不该做的建议，但它并没有真正回答你应该做什么的问题。关于REST的重要一点是统一界面的想法。换句话说，GET，PUT，POST和DELETE应该完全按照您认为应该做的。 GET检索资源的表示，PUT更新，POST创建和删除删除。

最重要的问题是如何描述您的数据及其含义。您始终可以选择定义XML Schema或类似的方法，并从架构生成文档。就个人而言，我发现机器生成的文档都没有用。

在我看来，最好的数据格式包含广泛的人类可读文档和示例。这是我知道如何正确描述语义的唯一方法。我喜欢使用Sphinx来生成此类文档。

Answer 4

我不确定您是否要求使用工具来帮助您，或者您是在询问最佳做法（或两者）。

就最佳实践而言，REST文档同样适用于其他软件文档 - 提供一个广度良好的登录页面（即，逻辑组织的资源列表，其中包含关于它们的作用及其URI的信息）深入分析页面，通过示例深入解释每个人的工作内容。 Twitter的REST API有很好的文档记录，它应该是一个很好的模型。

Twitter API main page

Sample drilldown of one resource

我真的很喜欢这个下钻页面。它列出了您需要的所有参数，并列出了每个参数。它有一个侧栏，列出了支持的类型。它具有相关页面和具有相同标签的其他页面的链接。它有一个样本请求和响应。