Fatal编程技术网
  • api/
  • 记录/生成RESTful/HTTP RPC API引用的最佳工具是什么？

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

api rest

记录/生成RESTful/HTTP RPC API引用的最佳工具是什么？,api,rest,documentation-generation,Api,Rest,Documentation Generation,关于基于REST/HTTP的API等，已经发布并回答了许多问题，但似乎没有一个关于以下问题的详细信息： 哪些工具可用于记录HTTP-RPC API？ 哪些工具是最好的 2009年1月的一个类似问题（针对ASP.NET）也可以找到，但没有答案 我正在为专业和个人项目开发几个API（.NETMVC/OpenRasta、PHP、Coldfusion等），我还没有找到任何特别的东西来帮助记录这些API。我不是在寻找基于代码解析/清理之类的自动生成。您可能已经知道，基于RESTful/HTTP的API应该

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

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

2009年1月的一个类似问题（针对ASP.NET）也可以找到，但没有答案

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

体面的工具可能具有的功能：

  • 指定URL/URI格式/结构
  • 请求/响应格式和方法（GET/POST/etc、XML/JSON/etc）
  • 对端点/API调用进行分类（例如在身份验证下对多个调用进行分组）
  • 自动生成静态参考文件/文档，如以下示例所示
  • 包括示例、测试用例等
下面是一些我认为体面的API文档/参考文献的例子：

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

  • 指定URL/URI格式/结构
  • 请求/响应格式和方法（GET/POST/etc、XML/JSON/etc）
  • 对端点/API调用进行分类（例如在身份验证下对多个调用进行分组）
RESTful API文档是关于记录所使用的媒体类型及其相关应用程序语义的。你应该找一些看起来更像的东西

您给出的示例是基于HTTP的RPC API，这就是为什么它们需要这种类型的端点文档。他们只是名义上的平静。现在，为什么人们不创建工具来自动记录基于HTTP的RPC API，我真的不能告诉你。可能是因为编写这些API的人忙于维护它们，所以他们没有时间编写文档工具

经过大量研究，我发现这并不是一个能完全满足我需求的工具。有许多工具在很大程度上是朝着正确方向迈出的一步，但通常是特定于语言的，它们不生成HTTP API/RPC参考文档，而是生成代码/库/API参考文档

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

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

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

如果您使用的是用于PHP的Symfony2框架，下面是自动生成RESTful服务文档的现成捆绑包：

这种生成器有一点我不喜欢，那就是缺少翻译，因此，如果您想提供通过RESTful服务在多种语言上公开的API文档，那是不行的。

我理解您的观点，我不想争论语义，因为exmaple在这个问题上具有误导性。我个人认为RESTful应用程序和RESTful API是两个不同的实体。然而，为了理智起见，我将更新我的问题，使之更加具体-1：教条式的胡说八道而不是实用性。RESTAPI也需要文档。出于验证目的，我希望收到哪些HTTP状态码？如何处理身份验证？我应该使用哪个字符集？有效载荷是什么样子的？它的任何部分都是可选的吗？单个组件接受哪种类型的数据？您注意到，作为应用程序语义，这些东西值得记录，但您似乎否认可以轻松记录这些内容的工具应该存在，而是认为工具的存在意味着您选择了错误的解决方案。@jesper验证状态代码：400。身份验证已处理，但www authenticate标头表示已处理。媒体类型或链接关系将告诉您负载的外观。Charset？媒体类型文档。可选组件、媒体类型文档。如果一个工具可以神奇地记录它，那么你很可能最终会得到一个文档，上面写着“GET/Customer去检索一个客户”。该IMHO是100%冗余的。在RESTful系统中，资源的发现应该是动态的，而不是在文档中。@Darreller:您一定在谈论另一种RESTAPI。我完全同意这样的伪文档是完全没有价值的。但这不是最初的问题；它是“如何在我的调用列表中附加合理的文档”，在REST上下文中，它是一个资源和允许操作的列表。REST不局限于HATEOAS，你的观点更适用于此。@Jesper“REST不局限于HATEOAS”显然发明这个术语的人不同意：看起来很有希望，但我自己没有用过。另外，它是特定于Java的，尽管它背后的思想可能会被移植到其他语言中……如果我使用Java:P，那将是非常棒的。但是，它肯定会对未来的Java项目有用，所以感谢您的链接！我为RESTful API文档创建了一个简单的模板：也许它对您也很有用。如果n