我正在为新的内部Web服务编写RESTful API规范.这不是很长很简单,但即便如此,这是我第一次使用严格的REST(而不是出于实际原因作弊 - 避免PUT,DELETE因为它们是PHP的痛苦,等等).我想知道是否有任何标准方法或最佳实践来记录REST接口？我希望团队的其他成员能够一目了然地理解它,对于任何想要编写客户端的人来说,如果不了解底层代码就能够这样做.
当然,REST API理想情况下应该使用HATEOAS并且是超文本驱动的(大量使用媒体类型),但也有简单的人性化文档供开发人员使用,这是有帮助的.
一些有助于生成这样的文档的特定工具:
昂首阔步
用于描述REST API的开放规范[ github ]
自动生成工具
文档
您的API代码
捐赠给OpenAPI计划,并于2015年更名为OpenAPI
Mashery
一个开源项目[ github ]
生成工具
文档
API的探索界面
蜂房和API蓝图
在降价时在DSL中写入API描述
自动生成工具
文档
模拟服务器
似乎专注于ruby + mac devs
肾错构瘤
描述REST API的规范[ github ]
WADL
使用XML编写可发现的API文档的规范
一些讨论比较WSDL和WADL
APIgee
具有一些文档功能的商业产品
3比例
具有一些文档功能的商业产品
miredot
商业REST API文档生成器
特定于Java
我一直在使用http://apiary.io,这非常好.您还可以将API文档导出到github.
在罗伊的帖子中,他说
REST API应该花费几乎所有的描述性工作来定义用于表示资源和驱动应用程序状态的媒体类型,或者为现有标准媒体类型定义扩展关系名称和/或启用超文本的标记.在媒体类型的处理规则的范围内(并且在大多数情况下,已经由现有媒体类型定义)应该完全定义用于描述在感兴趣的URI上使用什么方法的任何努力.
一个好的ReST文档意味着记录您的媒体类型和仅媒体类型.
在典型的场景中,您将生成如下文档:
文档中描述了各种资源的链接,可以通过在书签URI(通常是服务器的根目录,http://www.acme.org)上向服务器发出GET或HEAD请求来查找,并查找HTTP链接头:
Link:
其中rel部分是链接关系,并且xxx是已建立关系的URI.
本文档定义了以下关系名称:
http://rel.acme.org/services 链接关系描述了可以导航的链接列表.
http://rel.acme.org/customers 使用此关系的链接是客户列表.
这application/vnd.acme.services+xml是一个带有xml序列化的文档,它描述了应用程序可能要处理的链接列表.
这applcation/vnd.acme.customers+xml是一个带有xml描述客户的序列化的文档.
等等...
关键是要让开发人员遵循您定义的链接.首先找到索引的链接,以便他们可以获取他们可以导航到的内容列表.
一旦他们发现该文档,他们就会发现他们可以在某个Uri上看到一个客户列表,并且可以对其进行GET反对.
如果他们找到感兴趣的客户,他们可以按照中定义的链接/customers/customer/@href发布GET并检索该客户的代表.
从那里,您的媒体类型可以使用更多链接嵌入用户可用的操作.您还可以选择在资源上发出OPTIONS请求以了解是否允许删除资源,或者如果您可以在修改后保存文档,则可以选择PUT.
所以一个好的文档永远不会:
给静态链接
进行交互,例如"您可以使用此媒体类型向客户发布POST,这将意味着移动操作".客户端应该仅针对Customer发出POST,因为您的XML文档已经以这种方式指定了它.
所有这一切的要点是实现客户端和服务器之间的最小耦合.客户端可以非常智能地显示和发现资源(显示表单和上帝知道还有什么),但对于实际工作流程是完全愚蠢的:服务器决定.
京公网安备 11010802040832号 | 京ICP备19059560号-6 