用于记录RESTful API的标准方法

Question

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

Answer 1

当然，REST APIs should ideally use HATEOAS and be hypertext driven（大量使用媒体类型），但也有简单的人性化文档供开发人员使用，这是有帮助的。

一些有助于生成此类文档的特定工具：

• Swagger
  • 用于描述REST API [github]
  的开放规范
  • 自动生成工具
    • 文档
    • 您的API代码
  • 捐赠给OpenAPI倡议和renamed OpenAPI in 2015
• Mashery
  • 开源项目[github]
  • 用于生成的工具
    • 文档
    • API的探索界面
• Apiary和API Blueprint
  • 在标记下的DSL中写下API描述
  • 自动生成工具
    • 文档
    • 模拟服务器
  • 似乎专注于ruby + mac开发
• RAML
  • 用于描述REST API [github]
  的规范
• WADL
  • 使用XML编写可发现的API文档的规范
  • 一些讨论comparing WSDL and WADL
• APIgee
  • 具有一些文档功能的商业产品
• 3scale
  • 具有一些文档功能的商业产品
• miredot
  • 商业REST API文档生成器
  • 特定于Java

Answer 2

我一直在使用http://apiary.io，这非常好。您还可以将API文档导出到github。

Answer 3

在Roy的帖子中here他说

  

REST API应该花费几乎全部   它在定义中的描述性努力   用于表示的媒体类型   资源和驾驶应用   状态，或定义扩展   关系名称和/或   支持超文本的现有标记   标准媒体类型。任何努力都花了   描述在什么方面使用什么方法   感兴趣的URI应该是完全的   在范围内定义   处理媒体类型的规则   （并且，在大多数情况下，已经定义了   按现有媒体类型）。

Answer 4

良好的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。

链接关系

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

• http://rel.acme.org/services 链接关系描述了可以导航的链接列表。
• http://rel.acme.org/customers 使用此关系的链接是客户列表。

媒体类型

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。

所以好的文档永远不会出现：

• 提供静态链接
• 进行交互，例如“您可以使用此媒体类型向客户发布POST，这将意味着移动操作”。客户端应仅针对Customer发出POST，因为您的XML文档已按此方式指定。

所有这一切的目的是实现客户端和服务器之间的最小耦合。客户端可以非常智能地显示和发现资源（显示表单和上帝知道还有什么），但对于实际工作流程是完全愚蠢的：服务器决定。

Answer 5

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

有许多工具和资源可供使用WADL，包括：

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

提示：通过使用XHTML命名空间包含HTML元素，尝试在WADL文档的doc元素中包含人类可读的文档，如描述，概念，入门，使用技巧等。它可以产生很大的不同！

Answer 6

最初，我们去了资源的静态文档，但只需要提出太多问题。最后，我们开始使用IO / Docs使用Live文档页面（实际上是fork）。 工作得很好。

Answer 7

您可能会发现rest-tool有用。

它遵循与语言无关的方法来编写RESTful API的规范，模拟实现和自动化单元测试。它还提供了一本烹饪书，但它处于一个很早的阶段，但其内容却在不断增长。

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

Answer 8

要创建理解/文档，并不总是需要重量级解决方案。 （伟大的）重量级工具的例子有：IO / Docs / Apigee（虽然很棒的工具）。

对于已经有docchain设置的小项目（doxygen / phpdoc / phpdoctor / custom / etc），我使用以下的shellcript将页面包含在完整生成的文档中：

https://gist.github.com/4496972

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

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