API 设计: RAML、Swagger、Blueprint三者的比较

简介: API设计工具中常常会拿RAML、Swagger、Blueprint这三种工具进行讨论比较,它们都是用来描述和辅助API开发的,只是它们之间的侧重有所不同。 RAML RAML(RESTful API Modeling Language 即 RESTful API 建模语言)是对 RESTful API的一种简单和直接的描述。

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开发的工具,这里特别推荐一下raml2htmlapi-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

 

相关文章
|
7天前
|
数据可视化 Linux API
如何在Linux使用docker部署Swagger Editor并实现无公网IP远程协同编辑API文档
如何在Linux使用docker部署Swagger Editor并实现无公网IP远程协同编辑API文档
|
7天前
|
JSON Dubbo 测试技术
逐步教你如何在Postman中导入Swagger API
在现代软件开发中,Swagger 和 Postman 作为 API 设计、开发和测试的利器,都被广泛应用。可以将 Swagger 定义的 API 导入到 Postman 中,充分利用 Postman 强大的测试特性对接口进行深入测试。
|
7天前
|
数据可视化 Linux API
使用Docker安装部署Swagger Editor并远程访问编辑API文档
使用Docker安装部署Swagger Editor并远程访问编辑API文档
66 0
|
6月前
|
Java API Maven
淘东电商项目(05) - Swagger及网关统一管理API
淘东电商项目(05) - Swagger及网关统一管理API
76 0
|
7月前
|
安全 Java API
解决 Swagger API 未授权访问漏洞:完善分析与解决方案
Swagger 是一个用于设计、构建、文档化和使用 RESTful 风格的 Web 服务的开源软件框架。它通过提供一个交互式文档页面,让开发者可以更方便地查看和测试 API 接口。然而,在一些情况下,未经授权的访问可能会导致安全漏洞。本文将介绍如何解决 Swagger API 未授权访问漏洞问题。
|
7天前
|
Dubbo Java 测试技术
提升API文档品质:Swagger annotations (注解)使用教程
Swagger 提供的注解集是其框架中定义 API 规范和文档的重要工具。这些注解在代码里标注重要部分,为 Swagger 的解析工作铺路,进而生成详尽的 API 文档。开发者编写的注释能够被转换成直观的文档,并展现API端点、参数和响应等信息。这不仅提升了开发人员对 API 运作的理解与沟通,也使得测试和集成过程更加顺畅。
|
6月前
|
Java API Maven
微服务技术系列教程(27) - SpringCloud- Zuul整合Swagger管理微服务所有API
微服务技术系列教程(27) - SpringCloud- Zuul整合Swagger管理微服务所有API
61 0
|
7天前
|
开发框架 JSON .NET
初学者不会写接口怎么办?微软Visual Studio 2022无脑式API接口创建——Swagger一键导入APIKit快速测试
初学者不会写接口怎么办?微软Visual Studio 2022无脑式API接口创建——Swagger一键导入APIKit快速测试
98 0
|
7天前
|
数据可视化 Linux API
使用Docker安装部署Swagger Editor并远程访问编辑API文档
使用Docker安装部署Swagger Editor并远程访问编辑API文档
|
6月前
|
JSON Kubernetes API
kubernetes REST Api详解(导入Swagger至Postman)
kubernetes REST Api详解(导入Swagger至Postman)
139 1