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三者的比较的更多相关文章

  1. API生命周期第二阶段——设计：如何设计API（基于swagger进行说明）

    题外话 在新的项目中,推行了swagger用于对API的设计.以期待解决我们上篇博客中说到了一些现象,提升工作效率.那么,结合到当时和全项目组成员做培训,以及后续的给主要应用者做培训,以及当初自己接触 ...

  2. Web API设计方法论

    英文原文:A Web API Design Methodology 为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定 ...

  3. Web API设计方法论--比较完整的web api 开发过程

    为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在Web上维护 ...

  4. 如何真正实现由文档驱动的API设计？

    前言 本文主要介绍了一种新的开发思路:通过反转开发顺序,直接从API文档中阅读代码.作者认为通过这种开发方式,你可以更清楚地知道文档表达出什么以及它应该如何实现. 如果单从API文档出发,由于信息量不 ...

  5. （转）如何真正实现由文档驱动的API设计？

    前言 本文主要介绍了一种新的开发思路:通过反转开发顺序,直接从API文档中阅读代码.作者认为通过这种开发方式,你可以更清楚地知道文档表达出什么以及它应该如何实现. 如果单从API文档出发,由于信息量不 ...

  6. 在ASP.NET Core Web API上使用Swagger提供API文档

    我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...

  7. Core Web API上使用Swagger提供API文档

    在ASP.NET Core Web API上使用Swagger提供API文档   我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的AP ...

  8. 从草图绘制到实施交付：优秀API设计完整流程

    设计好的API是一项繁复的工作,但是优秀的设计是可以通过人为规划实现的,在本文中,我们将研究什么是好的设计以及如何在开发过程中实现它,还将介绍API设计的三个重要阶段:草图绘制,原型设计和交付实施,最 ...

  9. 移动App的REST API设计实践

    原文:http://www.jianshu.com/p/23cccb3a90b1 通讯协议 一些只是对服务器数据进行CRUD操作的App,通常采用HTTP协议,为了安全也可以采用HTTPS协议.IM软 ...

随机推荐

  1. 原生化：AnDevCon 2014 McVeigh 的主题演讲

    作者:Jeff McVeigh(Intel) 基于(至少部分)NDK的原生安卓应用程序占现在前1000 强的 60% 以上.该增长的原因很简单:开发商需要为用户提供超卓的体验(包括灵敏的反应.与丰富的 ...

  2. 浅谈UE4引擎

    首先要说的是,游戏开发是一项高度复杂的代码开发工作,编程语言只是最基本的知识,它涉及的内容还有计算机图形学.3D数学.物理学等复杂的学科.但是若需要学完这么多知识才能开发游戏,恐怕许多人都已经断气了, ...

  3. Python 在Windows下安装matplotlib

    windows下安装很麻烦,使用easy_install 安装报错  提示缺少freetype 和png 后经多方查询,最终安装成功 以下是安装过程 前提你的Python环境已经搭建好了 1.前提需要 ...

  4. SQL Server 控制锁升级

    背景知识: 锁升级的路线图.行--> 页 --> 区(extent)-->区(表分区)--> 表: alter table 控制锁的升级行为: 1.table SQL Serv ...

  5. Linux开发环境配置

      配置JDK: tar -xzvf jdk-7u71-linux-x64.tar.gz rm -f jdk-7u71-linux-x64.tar.gz 测试:java -version 配置Grad ...

  6. Life is short, you need Python

    今年四五月份的时候我打算学一门计算机语言. 计算机语言实在是很多,选哪一个? 其实这个选择就和去市场买菜类似,想明白了自己的需求才能做好决定.你想做什么饭,就去买什么菜.想做南瓜粥,就要去买南瓜,想要 ...

  7. 关于xxx.h file not found 的问题

    在引用第三方库的时候,经常会遇到xxx.h file not found的问题. 首先,我们要知道在引用第三方的时候,我们使用的第三方的库的类型. .a静态库 使用方式:#import "x ...

  8. JS框架~Angularjs

    无意中看到anytao的项目,工作台,使用了Angularjs框架,感觉在前端表现上用户体验比较好,于是就简单看了一下,原来使用很简单,或者说,人家把代码封装的很好,以至于开发人员调用时比较简单,呵呵 ...

  9. js/jquery中实现图片轮播

    一,jquery方法 <!DOCTYPE html> <html> <head> <meta http-equiv="Content-Type&qu ...

  10. Hadoop CLI MiniCluster

    CLI MiniCluster Use the climonicluster, users can simply start and stop a single-node hadoop cluster ...