RAML规范解读.pdfVIP

RAML 规范研究 1 RAML 是什么 RAML （RESTful API Modeling Language 即RESTful API 建模语言）是对RESTful API 的一种简 单和直接的描述。它是一种让人们易于阅读并且能让机器对特定的文档能解析的语言。RAML 是基于YAML ，符合1.2 版本规范，能帮助设计RESTful API 和鼓励对API 的发掘和重用，依 靠标准和最佳实践从而编写更高质量的API 。通过RAML 定义，因为机器能够看得懂，所以 可以衍生出一些附加的功能服务，像是解析并自动生成对应的客户端调用代码、服务端代码 结构， API 说明文档。 我们知道Web Service 有相应的WSDL 来描述它相应的Schema ，WSDL 就相当于对当前 的服务做了一个描述，Client 端可以据此生成相应的Proxy 代码, 因此WSDL 可以帮助Client 更容易的消费服务。对于RESTful API，却没有相应的“REST WSDL”，在这种情况下，RAML 应运而生，它可以对我们的API 做完整的描述，不管是对人或者是机器，都能以相对友好的 方式使用。 shiyuanstone 2014 年10 月8 日 2 RAML 规范 2.1 RAML 文件构成 上图是一个RAML 一个简单的例子。下面介绍一下RAML 的基本语法。完成一个RAML 具体步骤参见：/docs.html 整个RAML 文档可简单划分为“版本声明”、“API 元数据定义”、“公用属性定义”和“资 源方法定义”四部分构成。 元素 说明 示例 shiyuanstone 2014 年10 月8 日 RAML 版 每一个RAML 文件在第一 本声明 行都必须是RAML 版本的 声明 API 元数 整个API 的标题、版本、 据定义 API 基础url、相关文件 （documentation 属性） 公用属性 Schemas：用于定义请求 定义 参数或者响应结构； securitySchemas ：定义api 访问的安全机制； ressourceTypes：定义该属 性如同定义一个资源，可 以对其进行描述 （declaration ），方法和属 性的定义。在使用该资源 类型的资源会继承其性 质（例如方法）。 traits ：定义该属性如同定 义一个方法，可以包括方 法级属性，包括描述 （declaration ），头，查询 字符串参数，和响应。使 用这些traits 的方法会继 承其中的属性。 shiyuanstone 2014 年10 月8 日 资源 （resourc e ）和方法 （Action ） 定义 2.2 YAML 语法介绍 RAML 是基于YAML ，符合1.2 版本规范，所以文件的格式说明直接参考YAML 语法。 YAML 作为一种比 XML ，或者 JSON 都更为简单易读的序列化语言，正越来越多地被 人们所接受和喜欢，并应用于软件项目的开发中，比如：现实生活中的数据上程序中的序列 化表示，以及系统中的配置文件的书写。 YAML 的数据组织主要依靠的是空白，缩进，分行等结构。这使得 YAML 语言很容易上 手。 用 “# ”表示文档行注释的开始。如下图