用于记录/生成RESTful / HTTP RPC API的最佳工具是什么？

Question

关于基于REST / HTTP的API等已发布并回答了许多问题，但似乎没有关于以下问题的信息很多：

可用/用于记录HTTP-RPC API的工具有哪些？ 哪种工具最好？

从2009年1月开始可以找到类似的问题（特定于ASP.NET）here，但没有答案。

我正在开发专业和个人项目（.NET MVC / OpenRasta，PHP，Coldfusion等）的几个API，我没有找到任何特别的东西来帮助记录这些API。我不是在寻找基于代码解析/擦除或类似的东西的自动生成。您可能已经知道基于RESTful / HTTP的 API 应该是客户端和平台无关的;因此我希望任何文档工具都是一样的。

---

一个体面的工具可能具有的特征：

• 指定网址/ URI格式/结构
• 请求/响应格式和方法（GET / POST / etc，XML / JSON / etc）
• 对端点/ API调用进行分类（例如，在身份验证下对多个呼叫进行分组）
• 自动生成静态参考文件/文档，如下面的示例
• 包括示例，测试用例等

---

以下是我认为合适的API文档/参考文件的一些示例：

http://dev.twitter.com/doc/post/statuses/destroy/:id

http://www.salesforce.com/us/developer/docs/api_rest/index.htm

http://www.flickr.com/services/api/

Answer 1

SWAGGER可能值得您一试。我使用它来记录使用Jersey的java应用程序公开的REST入口点，但看起来你也可以将它与其他语言一起使用。

Answer 2

此类工具不存在的原因之一是因为RESTful API的文档不应包含以下任何项目：

• 指定网址/ URI格式/结构
• 请求/响应格式和方法（GET / POST / etc，XML / JSON / etc）
• 对端点/ API调用进行分类（例如，在身份验证下对多个呼叫进行分组）

RESTful API文档是关于记录所使用的媒体类型及其相关的应用程序语义。您应该期望生成看起来更像this的内容。

您提供的示例是基于HTTP的RPC API，这就是他们需要此类端点文档的原因。它们只是名义上的RESTful。现在，为什么人们不创建自动记录基于HTTP的RPC API的工具，我真的不能告诉你。也许是因为编写这些API的人忙于维护它们，以至于他们没有时间编写文档工具！

Answer 3

经过大量研究后，我发现这不是我想要的工具。有许多工具在正确的方向上迈出了一步，但通常是特定于语言的，并且不生成HTTP API / RPC参考文档，而是生成Code / Library / API参考文档。

因此，我计划从头开始创建我需要/设想的工具。如果我有什么要展示的话，我会更新我的答案。

Answer 4

你应该看看Swagger应用程序，正如@ zim2001已经提到的那样。它有一个Swagger-ui组件，它是一个简单的html和javascript应用程序，用于读取后端应用程序记录的json数据。有适用于多种语言的适配器，包括php和java。

如果您正在使用PHP的Symfony2框架，这里是可立即使用的捆绑包，用于自动生成RESTful服务文档：

• https://github.com/nelmio/NelmioApiDocBundle

我不喜欢这样的生成器的一件事是缺少翻译，所以如果你想提供在许多语言的RESTful服务上暴露的API的文档 - 你不能。