如何记录REST API？

Question

如何记录 REST API？不仅是关于资源的文档，而是真正了解请求中发送的数据和响应中返回的数据。仅知道某些内容期望发送 XML 并返回 XML，或者 JASN 等并不够用。你如何记录请求中发送的数据和响应中返回的数据？

目前我找到的最好的方法是使用 Enunciate 工具来记录 REST API 和数据元素。Enunciate 是否是这种类型工具的正确选择？我是否错过了其他提供此功能的工具，应该查看哪些工具？

我的 REST API 的使用者可能使用任何编程语言，例如 Python、Java、.NET 等。

- BestPractices

---

也许可以使用 [tag:wadl] + XML Schema？ - Tomasz Nurkiewicz

Answer 1

我决定在我的项目中采用Enunciate的方法。这似乎是REST API文档的事实标准。

- BestPractices

Answer 2

我有使用过Enunciate，它非常好用，但我不太喜欢它所生成的客户端。另一方面，我在我的最近几个项目中使用了swagger，它似乎符合我的需求，真的很酷，你应该试试！

更新于03/08/2016：看起来你可以使用Enunciate来构建swagger文档。请参见this。

- German Attanasio

---

FYI，Enunciate的当前版本还可以构建Swagger文档。 - user2163960

Answer 3

我可能错了，但是你似乎想要类似于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来生成这种类型的文档。

- Shawn H

Answer 4

我不确定您是在寻求辅助工具，还是想了解最佳实践（或两者兼备）。

就最佳实践而言，REST文档与其他软件文档一样 - 提供一个良好的着陆页，具有广度（即，按逻辑组织的资源列表及其URI的简介），并提供深入解释每个资源的钻取页面，包括示例。Twitter的REST API文档非常出色，应该是一个很好的模型。

Twitter API主页

一个资源的示例钻取页面

我真的很喜欢那个钻取页面。它列出了你需要的所有参数，并对每个参数进行了描述。它有一个侧边栏，列出了支持的类型。它链接到相关页面和具有相同标签的其他页面。它有一个样本请求和响应。

- smcg