logo标签列表

标准方法记录RESTful API

restdocumentation
74

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

可能是RESTful API文档的重复问题。 - cHao
1
可能是 RESTful API 文档 的重复。 - iankit
8个回答
50

当然，理想情况下REST API应该使用HATEOAS并且是超文本驱动（大量使用媒体类型），但为开发人员提供简单易懂的人性化文档也是有帮助的。

以下是一些有用的生成此类文档的特定工具：

  • Swagger
    • 一种描述REST API的开放规范[ github ]
    • 自动生成工具
      • 文档
      • API代码
    • 在2015年改名为OpenAPI并捐赠给OpenAPI倡议组织renamed OpenAPI in 2015
  • Mashery
    • 一个开源项目[ github ]
    • 生成工具
      • 文档
      • API探索界面
  • Apiary和API Blueprint
    • 使用markdown中的DSL编写API描述
    • 自动生成工具
      • 文档
      • 模拟服务器
    • 似乎专注于ruby+mac开发人员
  • RAML
    • 一种描述REST API的规范[ github ]
  • WADL
  • APIgee
    • 一种带有一些文档功能的商业产品
  • 3scale
    • 一种带有一些文档功能的商业产品
  • miredot
    • 商业REST API文档生成器
    • Java特定
1
你还应该将miredot http://www.miredot.com添加到列表中。 - java_geek
@java_geek 当然，感谢你的推荐。如果你有更多发现需要编辑的地方，请随意修改。 - turtlemonvh
API描述格式之间的转换也值得注意，例如https://github.com/lucybot/api-spec-converter和http://studio.restlet.com/。 - Erik Sundvall
13
我一直在使用http://apiary.io，它非常不错。你也可以将API文档导出到github。
这不是在记录如何构建URI吗？这似乎违反了HATEOAS的原则吧？ - Myobis
9
在Roy的文章（这里）中，他指出：
REST API应该在定义用于表示资源和驱动应用程序状态的媒体类型或在定义扩展关系名称和/或现有标准媒体类型的超文本启用标记方面花费几乎所有的描述性工作。任何花费在描述在哪些URI上使用什么方法的努力都应完全在媒体类型的处理规则范围内定义（在大多数情况下，已由现有媒体类型定义）。
9
我理解你的意思是API应该自我说明并且逻辑清晰，不需要额外的文档。这很合理。但是在某个时候，我需要至少向人们提供一份允许调用的列表。我想知道是否有一种被认可的结构来创建这种列表。 - Samir Talwar
7
媒体类型确实需要文档记录，以下是一些例子：http://www.iana.org/assignments/media-types/application/但是你的文档不应包含 URL 列表，那么客户端开发人员可能会将这些 URL 硬编码到他们的应用程序中。 - Darrel Miller
5
也许我可以举一个有用的例子。想象一下去一个你不会说当地语言的外国国家，并去图书馆寻找一些信息。如果你求助并且那个人向你解释书架、ISBN编目，以及书籍包含页面，你需要从前往后阅读书本等概念，这些都是有效的信息，但你已经知道了。你需要的是有人翻译内容。在网络上，我们知道URL和超链接，我们知道如何使用HTTP动词。我们只需要了解你的内容细节。 - Darrel Miller
2
明白了。这也是我的直觉：提供每个调用“做什么”的详细说明，而不是“是什么”。我想没有标准的方法来做到这一点，但是，我猜随便试试也不会伤害任何人（别引用我说的话）。感谢您的帮助。 - Samir Talwar
1
@Mark 那么你只能通过实际查询端点并编写自己的文档来描述端点来开发每个端点？这似乎不太用户友好。 - Nick Coad
显示剩余2条评论
6
一个好的ReST文档意味着只记录你的媒体类型和仅限于你的媒体类型。
在典型情况下，您将制作一个如下所示的文档：
Acme Corp XML格式
链接发现
各种资源的链接描述在一篇文档中，可以通过在书签URI（通常是服务器的根目录http://www.acme.org）上发出GET或HEAD请求并查找HTTP链接标头来找到：
Link: <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请求来检索该客户的表示形式。

从那里开始，你的媒体类型可以嵌入可用于用户的操作，使用更多的链接。您还可以选择在资源上发出OPTIONS请求，以了解是否允许删除资源，或者PUT请求以在修改后将文档保存回去。

因此，良好的文档永远不应：

  • 提供静态链接
  • 提供交互，比如“您可以使用这种媒体类型在Customer上发出POST请求，这意味着移动操作”。客户端应仅因为您的XML文档已经这样指定了才对Customer发出POST请求。
所有这些的目的是实现客户端和服务器之间的最小耦合。客户端可以非常聪明地显示和发现资源（显示表单和其他等等），但对于实际工作流程完全不知情：服务器决定。
好的，所以我主要应该使用链接发现来记录API。我应该如何构建这样的XML文档？有什么链接吗？ - Samir Talwar
是的，您需要记录如何在媒体类型中发现链接和操作。至于如何做到这一点，请查看ATOM和HTML，那基本上就是您所需要的：一个<link rel= href=>以及一些传达您想要在客户端中显示的操作的方式。 - SerialSeb
5
在我的公司，我们一直很高兴地使用WADL，即Web应用程序描述语言。维基百科描述它为：“一种基于XML的文件格式，提供了一个可读取HTTP Web应用程序的机器说明”。我发现原始的WADL易于编写、阅读和理解，并且可以直接映射到RESTful概念。官方项目提供了简单的规范、XSD和RELAX NG模式以及Java工具。
有许多工具和资源可用于处理WADL，包括：
  • wadl_stylesheets，用于从WADL文件创建HTML文档的XSLT样式表
  • Restlet，一个用于构建RESTful服务器和客户端的Java框架，包括一个WADL扩展
一个提示：尝试在WADL文档的doc元素中包含可读的人类文档，例如描述、概念、入门介绍、使用技巧等，通过包含HTML元素并使用XHTML命名空间。这可以大大提高文档的可读性！
1
Rest-discuss中的一场持续讨论[1]表明，许多REST倡导者认为使用WADL没有太大优势。[1] http://tech.groups.yahoo.com/group/rest-discuss/message/12680 - Darrel Miller
1
我已经研究了WADL，但它似乎更倾向于机器解析而非文档编写。我不需要告诉计算机如何处理API - 这只需要编写一次。我确实需要告诉人们如何编写客户端，所以人是我的主要受众。 - Samir Talwar
您还可以使用WADL生成客户端存根，适用于强类型语言。例如，请查看wadl2java。 - dso
3
你可能会发现 rest-tool 很有用。
它采用面向语言的方法编写规范、模拟实现和自动化单元测试 RESTful API。它也提供了一个菜谱，不过它还处于早期阶段，但其内容正在不断增加。
你刚刚描述的服务可以立即使用，因此它也很适合进行实验。
2

最初，我们采用了静态文档的方式来记录资源，但是后来收到了太多的问题。最终，我们转而使用IO/Docs创建实时文档页面（实际上是分支）。效果非常好。

1
为了创建理解/文档，不一定需要使用重量级的解决方案。虽然IO/Docs和Apigee是很好的工具，但它们属于重量级工具。
对于已经设置好文档链（doxygen/phpdoc/phpdoctor/custom等）的小型项目，我使用以下shell脚本将页面包含在完整生成的文档中：

https://gist.github.com/4496972

一个演示：http://pastie.org/5657190 它只是在您的源代码中使用自定义注释标签。这也可以是记录任何源代码（语言）的好起点。
1
最好在此处包含答案的基本部分，并提供参考链接。 - j0k
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接