用于记录 RESTful API 的标准方法

我正在为一个新的内部 Web 服务编写一个 RESTful API 规范。它不是很长，也不是很简单，但即便如此，这还是我第一次使用严格的 REST (而不是出于实际原因作弊——避免使用 PUT和 DELETE，因为它们是 PHP 中的痛苦，等等)。我想知道是否有任何标准方法或最佳实践来记录 REST 接口？我希望团队的其他成员能够一目了然地理解它，并且希望任何想要编写客户端的人都能够在不理解底层代码的情况下编写客户端。

61182 次浏览
小开

在罗伊的职位 给你他说

一个 REST API 应该花费几乎所有 它在定义 用于表示 资源及驾驶应用 国家，或在定义扩展 关系名称及/或 现有的支持超文本的标记 标准的媒体类型 描述对什么使用什么方法 感兴趣的 URI 应该完全是 范围内定义的 媒体类型的处理规则 (而且，在大多数情况下，已经定义了 现有媒体类型)。

小开

在我的公司，我们一直很高兴使用 WADL，Web 应用程序描述语言。Wikipedia 描述将其描述为: “一种基于 XML 的文件格式，提供了基于 HTTP 的 Web 应用程序的机器可读描述”。我发现原始 WADL 易于编写、阅读和理解，并且它直接映射到 RESTful 概念。官方项目提供了一个简单的规范、 XSD 和 RELAXNG 模式以及 Java 工具。

现有一些与世界反歧视联盟合作的工具和资源，包括:

  • WADL _ stylesheets ，XSLT 样式表从 WADL 文件创建 HTML 文档
  • Restlet 是一个用于构建 RESTful 服务器和客户端的 Java 框架，它包含一个 WADL 扩展

提示: 尝试在 WADL 文档的 doc元素中包含 HTML 元素，使用 XHTML 名称空间，包含人类可读的文档，如描述、概念、入门、使用提示等。它可以有很大的不同！

小开

一个好的 ReST 文档意味着记录您的媒体类型，并且只记录您的媒体类型。

在一个典型的场景中，您将生成如下文档:

Acme Corp XML 格式

链接发现

通过向书签 URI (通常是服务器的根 http://www.acme.org)上的服务器发出 GET 或 HEAD 请求，并寻找 HTTP 链接头，可以在文档中找到指向各种资源的链接:

链接: < xxx > ; rel = “ http://rel.acme.org/services";type=application/vnd.acme.services+xml”

其中 rel部分是链接关系，而 xxx是已建立关系的 URI。

链接关系

本文档定义了以下关系名称:

媒体类型

application/vnd.acme.services+xml是一个带有 xml序列化的文档，它描述了应用程序可能需要处理的链接列表。

<links>
<link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>

applcation/vnd.acme.customers+xml是一个带有描述客户的 xml序列化的文档。

文件范例:

<customers>
<customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>

等等。

关键是给开发人员提供一种方法来跟踪您定义的链接。首先找到到 索引的链接，这样他们就可以得到他们可以导航到的东西的列表。

一旦他们发现了这个文档，他们就会发现他们可以在某个 Uri 上看到一个客户列表，并且可以对它执行 GET操作。

如果他们找到感兴趣的客户，他们可以按照 /customers/customer/@href中定义的链接并发出 GET来检索该客户的表示。

从那里，您的媒体类型可以使用更多的链接嵌入用户可用的操作。您还可以对资源发出 OPTION 请求，以了解是否允许删除资源，或者如果修改后可以保存文档，则可以使用 PUT。

因此，一份好的文档永远不会:

  • 给出静态链接
  • 给予交互，如“您可以发布 POST 对客户与这种媒体类型，这将意味着移动操作”。客户端应该针对 Customer 发出 POST，因为您的 XML 文档已经以这种方式指定了它。

所有这些的关键是实现客户端和服务器之间的最小耦合。客户机可以非常聪明地显示和发现资源(显示表单和上帝知道的其他东西) ，但是对于实际的工作流程是什么完全是愚蠢的: 服务器决定。

小开

为了创建理解/文档，并不总是需要重量级的解决方案。

对于已经有 docchain 设置的小项目(doxygen/phpdoc/phpdoctor/custom/etc) ，我使用以下 shell 脚本将页面包含在完整生成的文档中:

Https://gist.github.com/4496972

演示: http://pastie.org/5657190

它只是在源代码中使用自定义注释标记。 它也可以作为记录任何源代码(语言)的一个很好的起点。

小开

我一直在使用 http://apiary.io，它非常不错，你也可以将 API 文档导出到 github。

小开

最初，我们使用的是静态的资源文档，但只是必须回答太多的问题。最终，我们转向使用 IO/Docs (实际上是 叉子)的 Live 文档页面。 工作很顺利。

小开

你可能会发现 休息工具很有用。

它遵循一种语言无关的方法来编写规范、模拟实现和 RESTful API 的自动化单元测试。它也提供了一本烹饪书，然而，它是在一个非常早期的阶段，但其内容是不断增长的。

您刚才描述的服务可以立即使用，因此它也很适合于实验。

小开
最佳答案

当然，REST API 理想情况下应该使用 HATEOAS 并且是超文本驱动的(使用了大量的媒体类型) ，但是拥有简单的人性化的文档供开发人员使用是很有帮助的。

一些特定的工具可以帮助生成如下文档:

  • 斯威格
  • 玛莎莉
    • 一个开源项目[ Github]
    • 生成工具
      • 文件
      • API 的探索接口
  • API Blueprint
    • 在标记内用 DSL 编写 API 描述
    • 自动生成工具
      • 文件
      • 模拟服务器
    • 似乎是专注于 Ruby + Mac 开发
  • RAML
    • 描述 REST API 的规范[ Github]
  • WADL
    • 用 XML 编写可发现 API 文档的规范
    • 一些讨论
  • 阿皮吉
    • 具有一些文档特性的商业产品
  • 三级
    • 具有一些文档特性的商业产品
  • Miredot
    • 商用 REST API 文件产生器
    • 爪哇特有的

提交答案