为 RESTful/HTTP RPC API 记录/生成参考的最佳工具是啥？ [关闭]

Posted 2023-02-16

【中文标题】为 RESTful/HTTP RPC API 记录/生成参考的最佳工具是啥？ [关闭]

【英文标题】：What is the best tool for documenting/generate reference for a RESTful/HTTP RPC API? [closed]为 RESTful/HTTP RPC API 记录/生成参考的最佳工具是什么？ [关闭]

【发布时间】：2011-06-06 15:15:56

【问题描述】：

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

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

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

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

---

一个不错的工具可能具有的功能：

指定 URL/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/

【问题讨论】：

lunatech-labs.com/open-source/jax-doclets 看起来很有希望，但我自己没有使用过。此外，它是特定于 Java 的，尽管它背后的想法可能会被移植到其他语言......

如果我使用 Java 那就太好了 :P 但是，它肯定对未来的 Java 项目很有用，所以谢谢你的链接！

我为 RESTful API 文档创建了一个简单的模板：github.com/berb/rest-doc-template 也许它对您也有用。如果没有，您可能想要分叉并将其用作基础。

RESTful API 文档的另一个很好的例子：twilio.com/docs/api/rest/call

关于一些选项的文章：apievangelist.com/2014/01/16/…

【参考方案1】：

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

【讨论】：

这几乎就是我想要的。谢谢:)

【参考方案2】：

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

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

RESTful API 文档是关于记录使用的媒体类型及其相关的应用程序语义。您应该希望制作看起来更像 this 的东西。

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

【讨论】：

我明白你的意思，我不想争论语义，例如en.wikipedia.org/wiki/Restful 在这个问题上相当误导。就我个人而言，我会将 RESTful 应用程序和 RESTful API 区分为两个不同的实体。但是，为了理智起见，我会更新我的问题以更具体！

-1：教条式的夸夸其谈的实用性。 REST API 也需要文档。出于验证目的，我应该收到哪些 HTTP 状态代码？如何处理身份验证？我应该使用哪个字符集？有效载荷是什么样的？它的任何部分是可选的吗？各个组件接受什么样的数据？你注意到这些东西，作为应用程序语义，值得记录，但你似乎否认应该存在一个可以用来轻松记录这些的工具，取而代之的是意味着一个工具的存在意味着你已经选择了错误的解决方案。

@jesper 用于验证目的的状态代码：400。身份验证已处理，但 www-authenticate 标头显示它是。媒体类型或链接关系都会告诉您有效负载的外观。字符集？媒体类型文档。可选组件，媒体类型文档。如果一个工具可以神奇地记录它，那么你很可能最终会得到说“GET /Customer toretrieve a Customer”的文档。恕我直言，这是 100% 多余的。在 RESTful 系统中，资源的发现应该是动态的，而不是在文档中。

@DarrelMiller：您一定是在谈论另一种 REST API。 Twitter's API documents all of this。我完全同意这样的伪文档完全没有价值。不过，这不是最初的问题。它是“我如何将合理的文档附加到我的调用列表中”，在 REST 上下文中将是资源列表和允许的操作。 REST 不限于 HATEOAS，您的积分更适用。

@Jesper "REST 不限于 HATEOAS" 显然发明这个词的人不同意：roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

【参考方案3】：

经过大量研究，我发现这不是完全符合我要求的工具。有许多工具朝着正确的方向迈出了一大步，但通常是特定于语言的，并且不会生成 HTTP API/RPC 参考文档，而是生成代码/库/API 参考文档。

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

【讨论】：

此工具创建的任何更新？

我已经为该工具创建了规范和数据架构，但遗憾的是尚未开始构建它。

【参考方案4】：

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

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

https://github.com/nelmio/NelmioApiDocBundle

我不喜欢此类生成器的一件事是缺乏翻译，因此如果您想提供通过多种语言的 RESTful 服务公开的 API 的文档 - 您不能。