REST建模语言RAML介绍

原创文章转载请注明出处：@协思, http://zeeman.cnblogs.com

 

RAML是什么?

 

RAML是一种简洁的RESTful API描述性语言，它基于 YAML和JSON这样的公开标准构建。通过RAML定义，可以生成客户端调用代码和服务端代码结构，创建API说明文档。

 

我们知道Web Service有相应的WSDL来描述它相应的Schema，WSDL就相当于对当前的服务做了一个描述，Client端可以据此生成相应的Proxy代码, 因此WSDL可以帮助Client更容易的消费服务。

 

对于RESTful API，却没有相应的“REST WSDL”，在这种情况下，RAML应运而生，它可以对我们的API做完整的描述，不管是对人或者是机器，都能以相对友好的方式使用。

 

RAML能帮助我们做什么?

 

RAML可以帮助你组织：

 

1.基本信息。描述RESTful API的关键点，比如名字、标题、路径等。

 

2.用户文档。描述技术支持性文档帮助用户更方便的消费API，通过文档生成器创建PDF或者HTML。

 

3.资源。描述如何规范RESTful资源，资源的方法和Schema，以及资源之间的交互。

怎样使用RAML设计API?

 

在线设计器：http://www.apihub.com/raml/api-designer

目前已经支持关键字自动提示，自动完成，语法错误检测，实时预览，功能相对完善，程序员使用起来很容易上手。

 

RAML设计器和解析器都是github的开源项目，我们可以将他们集成到自己的产品中。

 

前文看到的文档就是利用RAML解析器生成的，它是一个压缩后大约240k的Javascript文件，可以加载到浏览器或者Node.js中运行，利用解析器可以Load指定的RAML文件生成HTML文档。

 

RAML相关的工具和资源在哪里?

 

官方网站：http://raml.org 

规范文档：http://raml.org/spec.html

设计器：https://github.com/mulesoft/api-designer

解析器：https://github.com/raml-org/raml-js-parser