API 设计: RAML、Swagger、Blueprint三者的比较
API设计工具中常常会拿RAML、Swagger、Blueprint这三种工具进行讨论比较,它们都是用来描述和辅助API开发的,只是它们之间的侧重有所不同。
RAML
RAML(RESTful API Modeling Language 即 RESTful API 建模语言)是对 RESTful API的一种简单和直接的描述。它是一种让人们易于阅读并且能让机器对特定的文档能解析的语言。RAML 是基于 YAML,能帮助设计 RESTful API 和鼓励对API的发掘和重用,依靠标准和最佳实践从而编写更高质量的API。通过RAML定义,因为机器能够看得懂,所以可以衍生出一些附加的功能服务,像是解析并自动生成对应的客户端调用代码、服务端代码 结构, API说明文档。
上面这段引用自网络,这是我见到的对RAML最清晰的描述了。RAML本质上可以理解为一种文档的书写格式,这种格式是特别针对API的,就像Markdown是针对HTML的一样。并且RAML也同样具备了像Markdown那样的可读性,即使是看RAML源码也能很快明白其意图。另外基于RAML语言,有不少辅助API开发的工具,这里特别推荐一下raml2html
与api-console
,它们都可以将raml源文件转换成精美的doc文档页面,其中raml2html
转换结果是静态的,api-console
则可以生产可直接交互的api文档页面,有些类似后面要说的Swagger。
raml2html输出的文档
api-console生成的结果,可以直接在线编辑RAML后解析,也可以给出RAML文件远程读取解析
Swagger
Swagger与RAML相比,RAML解决的问题是设计阶段的问题,而Swagger则是侧重解决现有API的文档问题,它们最大的不同是RAML需要单独维护一套文档,而Swagger则是通过一套反射机制从代码中生成文档,并且借助ajax可以直接在文档中对API进行交互。因为代码与文档是捆绑的所以在迭代代码的时候,就能方便的将文档也更新了。不会出现随着项目推移代码与文档不匹配的问题。另外Swagger是基于JSON进行文档定义的。
Swagger生成的文档
API Blueprint
API Blueprint是使用Markdown来定义API的,Markdown相比前面两个RAML、JSON门槛又降低了一大截。同时API Blueprint与前面的Swagger、RAML一样也能提供可视化的文档界面与Mock Server的功能。不过其Mock能力比较弱。
工具就是这样的,具体到使用还得看你的应用场景,对于个人开发,小项目我比较喜欢Swagger,代码与文档一同维护省太多事儿了,但对于团队开发,使用RAML这种建模语言进行设计与沟通是不错的选择,并且RAML的Mock和文档能力也不弱,麻烦就在于增加维护成本,不过既然都团队了这个也就不是什么问题了。至于API Blueprint说实话没怎么用过,不过感觉用Markdown挺美好的。
-完-
你还可以看:
Rails: 使用Swagger来维护Grape API文档
参考引用
http://dwz.cn/2emOPO
http://dwz.cn/2ep85K
http://www.wtoutiao.com/p/1034TaC.html
API 设计: RAML、Swagger、Blueprint三者的比较的更多相关文章
- API生命周期第二阶段——设计:如何设计API(基于swagger进行说明)
题外话 在新的项目中,推行了swagger用于对API的设计.以期待解决我们上篇博客中说到了一些现象,提升工作效率.那么,结合到当时和全项目组成员做培训,以及后续的给主要应用者做培训,以及当初自己接触 ...
- Web API设计方法论
英文原文:A Web API Design Methodology 为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定 ...
- Web API设计方法论--比较完整的web api 开发过程
为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在Web上维护 ...
- 如何真正实现由文档驱动的API设计?
前言 本文主要介绍了一种新的开发思路:通过反转开发顺序,直接从API文档中阅读代码.作者认为通过这种开发方式,你可以更清楚地知道文档表达出什么以及它应该如何实现. 如果单从API文档出发,由于信息量不 ...
- (转)如何真正实现由文档驱动的API设计?
前言 本文主要介绍了一种新的开发思路:通过反转开发顺序,直接从API文档中阅读代码.作者认为通过这种开发方式,你可以更清楚地知道文档表达出什么以及它应该如何实现. 如果单从API文档出发,由于信息量不 ...
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
- Core Web API上使用Swagger提供API文档
在ASP.NET Core Web API上使用Swagger提供API文档 我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的AP ...
- 从草图绘制到实施交付:优秀API设计完整流程
设计好的API是一项繁复的工作,但是优秀的设计是可以通过人为规划实现的,在本文中,我们将研究什么是好的设计以及如何在开发过程中实现它,还将介绍API设计的三个重要阶段:草图绘制,原型设计和交付实施,最 ...
- 移动App的REST API设计实践
原文:http://www.jianshu.com/p/23cccb3a90b1 通讯协议 一些只是对服务器数据进行CRUD操作的App,通常采用HTTP协议,为了安全也可以采用HTTPS协议.IM软 ...
随机推荐
- TIANKENG’s restaurant--hdu4883
TIANKENG’s restaurant Time Limit: 2000/1000 MS (Java/Others) Memory Limit: 131072/65536 K (Java/O ...
- 03-树1. List Leaves (25)
Given a tree, you are supposed to list all the leaves in the order of top down, and left to right. I ...
- Mfgtool
For bootstrap mode, it refers to the communcation between the host and ROM codes through serial down ...
- SQL Server 对象
第一项:重命名对象 execute sp_rename @objname='Nums',@newname ='Numbers',@objtype ='object'; go 这里要特别小心 @ne ...
- Zigbee2007协议中文介绍
Zigbee2007中文介绍ZigBee2007规范定义了ZigBee和ZigBee Pro两个特性集,全新的ZigBee 2007规范建立在ZigBee2006之上,不但提供了增强型的功能而且在某些 ...
- 如何将Oracle安装为Linux服务
方法一:使用oracle自带的启动和关闭脚本 1. oracle用户修改/etc/oratab 文件: $ vi /etc/oratab orcl:/oracle/app/product/10.2.0 ...
- Google地图轨迹回放模拟
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/ ...
- linux学习方法之六
相信不少想学习linux的新手们正愁不知道看什么linux学习教程好,下面小编给大家收集和整理了几点比较重要的教程,供大家学习,如需想学习更多的话,可到wdlinux学堂寻找更多教程. 1.linux ...
- CvMat、Mat、IplImage之间的转换详解及实例
见原博客:http://blog.sina.com.cn/s/blog_74a459380101obhm.html OpenCV学习之CvMat的用法详解及实例 CvMat是OpenCV比较基础的函数 ...
- OC基础7:变量和数据类型
"OC基础"这个分类的文章是我在自学Stephen G.Kochan的<Objective-C程序设计第6版>过程中的笔记. 1.有时候初始化需要让对象带有初始值,那么 ...