RAML规范解读

shiyuanstone2014年10月8日RAML规范研究1RAML是什么RAML（RESTfulAPIModelingLanguage即RESTfulAPI建模语言）是对RESTfulAPI的一种简单和直接的描述。它是一种让人们易于阅读并且能让机器对特定的文档能解析的语言。RAML是基于YAML，符合1.2版本规范，能帮助设计RESTfulAPI和鼓励对API的发掘和重用，依靠标准和最佳实践从而编写更高质量的API。通过RAML定义，因为机器能够看得懂，所以可以衍生出一些附加的功能服务，像是解析并自动生成对应的客户端调用代码、服务端代码结构，API说明文档。我们知道WebService有相应的WSDL来描述它相应的Schema，WSDL就相当于对当前的服务做了一个描述，Client端可以据此生成相应的Proxy代码,因此WSDL可以帮助Client更容易的消费服务。对于RESTfulAPI，却没有相应的“RESTWSDL”，在这种情况下，RAML应运而生，它可以对我们的API做完整的描述，不管是对人或者是机器，都能以相对友好的方式使用。shiyuanstone2014年10月8日2RAML规范2.1RAML文件构成上图是一个RAML一个简单的例子。下面介绍一下RAML的基本语法。完成一个RAML具体步骤参见：整个RAML文档可简单划分为“版本声明”、“API元数据定义”、“公用属性定义”和“资源方法定义”四部分构成。元素说明示例shiyuanstone2014年10月8日RAML版本声明每一个RAML文件在第一行都必须是RAML版本的声明API元数据定义整个API的标题、版本、API基础url、相关文件（documentation属性）公用属性定义Schemas：用于定义请求参数或者响应结构；securitySchemas：定义api访问的安全机制；ressourceTypes：定义该属性如同定义一个资源，可以对其进行描述（declaration），方法和属性的定义。在使用该资源类型的资源会继承其性质（例如方法）。traits：定义该属性如同定义一个方法，可以包括方法级属性，包括描述（declaration），头，查询字符串参数，和响应。使用这些traits的方法会继承其中的属性。shiyuanstone2014年10月8日资源（resource）和方法（Action）定义2.2YAML语法介绍RAML是基于YAML，符合1.2版本规范，所以文件的格式说明直接参考YAML语法。YAML作为一种比XML，或者JSON都更为简单易读的序列化语言，正越来越多地被人们所接受和喜欢，并应用于软件项目的开发中，比如：现实生活中的数据上程序中的序列化表示，以及系统中的配置文件的书写。YAML的数据组织主要依靠的是空白，缩进，分行等结构。这使得YAML语言很容易上手。用“#”表示文档行注释的开始。如下图shiyuanstone2014年10月8日“”的作用，以缩进对齐来判断是否为一段文字，也就是说，一旦缩进与上一行不一致，则认为是一个新行。下面node1的例子中，第一行“Ther...door”，第二行“Please...floor”，第三行“So...So2”。用“|”表示之后的文字，每一行均为一个新行。YAML的设计者认为在配置文件中所要表达的数据内容有三种类型：标量(Scalar，如字符串和整数等)、序列（Sequence，如数组）和Mapping（类似hash的key/valuepair）。sequence型主要是用来表示数组类型的数据。下图描述了YAML中Sequence型数据的表示法shiyuanstone2014年10月8日mapping数据类型主要用来表示key:value对类型的数据。YAML描述方式见下图：用“-”来表示一些序列的项（Sequence），如下图里的产品（product）有两样东西（Basketball和SuperHoop）组织为一个序列；用“：”来表示一对项目（Map）里的栏目（Key）和其相应的值（Value），比如下图发票里的时间（date）的值是2001-01-23，这就是一个Map。shiyuanstone2014年10月8日使用“!include”来引入外部的文件（包括RAML，YAML和普通的txt文件），这样就可以将一个很大的RAML分成很多个部分。注意：被引入的文件不能再引用其他文件，即被引用的文件中不能再包括“!include”属性。这些就是YAML里最重要的语法了。如果想知道其他语法的细节可以参看YAML官方网页里的参考卡片（referencecard）：。注意缩进：缩进只能是两个空格为一级，不能是其他字符。2.3RAML属性定义2.3.1API元数据定义元素说明示例title必填。简要描述apiversion版本baseUriAPI访问的基础路径。shiyuanstone2014年10月8日RESTAPI的所有资源定义都是相基础访问路径的。protocols当前API所支持的访问协议，如果没有定义该属性值，则默认认为仅支持baseUri所采用的协议。mediaTypeAPI响应的默认媒体类型documentationAPI定义中可以包含一系列文档用于指导用户如何使用。两种实现方式1：直接在RAML文档中定义2：使用“!include”属性引入外部文件2.3.2元属性RAML规范中，用于描述像URI参数、查询参数（queryParameters）、表单参数（formParameters）、请求体（body）、请求和响应的头等集合属性的属性，我们称之为元属性。元素名称是否必须说明shiyuanstone2014年10月8日displayName可选参数指定参数的显示名称，如果没有定义，则显示属性的名称。description可选参数对指定的属性进行描述，例如对属性的用法、含义等进行描述type可选参数默认为string类型enum可选参数仅适用于string类型参数。提供参数有效值得枚举，必须为一个数组。如果定义了枚举类型，则API客户端和服务器必须对定义了该参数的属性进行验证，如果没有匹配值，则会报错。pattern可选参数仅适用于string类型参数。该参数为正则表达式，string类型参数必须匹配minLength可选参数仅适用与string类型参数，定义参数的最小长度maxLength可选参数仅适用于String类型参数，定义参数的最大长度minimum可选参数仅适用于number和integer类型参数，定义参数的最小值maximum可选参数仅适用于number和integer类型参数，定义参数的最大值example可选参数定义示例。repeat可选参数表明参数可以重复，如果这个参数可以被多次使用，那么repeat的值为‘true’，否则则为‘false’。required可选参数（除非有特别说明），用来表明该参数是否必需，如果是则为‘true’，否则为‘false’。default可选参数用来定义参数的默认值。举例如下图中查询参数“pagenumber”和“pagesize”的定义。shiyuanstone2014年10月8日2.3.3资源定义所有的资源标示符都是相对路径，必须以“/”开头。资源定义分为顶级资源和嵌套资源，嵌套资源即在已有资源定义内再定义资源。顶级资源的url路径相对于baseUrl属性。定义资源的相对路径可以使用含有参数的模板路径。下面的例子为定义一个顶级资源“/jobs”和一个含有变量的嵌套资源“/{jobId}”。可以使用“uriParameters”属性对资源标识符中的变量进行详细定义。2.3.4方法定义在RESTfulAPI中，所有的方法操作都是针对一个资源的。方法的名称必须是HTTP1.1规shiyuanstone2014年10月8日规范中定义的method中的一种。比较常用方法的有GET,,POST,PUT,DELETE。下图为查询和修改一本书的资源方法定义示例。其中get方法的响应体和put方法的请求体为json字符串，通过“body”属性定义。“body”属性作为一个hashmap，其中必须包括媒体类型作为key，如“application/json”、“text/xml”。form表单参数shiyuanstone2014年10月8日查询参数2.3.5重用属性定义资源和方法的定义存在重复性，比如一个API需要OAuth认证，这个API的所有资源和方法的定义必须包含“access_token”查询参数。针对这种场景可以定义重用属性，让其他资源或方法通过继承的方式来获取属性的设置。2.3.5.1资源类型resourceTypes定义资源类型如同定义一个资源，可以对其进行描述（declaration）、方法和属性的定义。定义资源时通过“type”属性定义所继承的资源类型，一个资源属于一个或零个资源类型。使用该资源类型的资源会继承其属性设置。资源类型定义shiyuanstone2014年10月8日资源类型使用2.3.5.2方法特征traits定义trait如同定义一个方法，可以包括方法级属性，包括描述（declaration），HTTP头，查询字符串参数和响应的定义。定义资源时通过“is”属性定义所使用的trait，一个方法可以拥有零个或多个trait。使用trait的方法会继承其中的属性设置。traits定义shiyuanstone2014年10月8日trait使用2.3.5.3结构模型schemasAPI方法的入参或者返回结果如果为json或者xsm格式，通常需要“schema”属性来定义该格式类型对应的结构。“schema”属性值既可以是结构模型的真实定义，也可以是之前所定义结构模型的名称。直接定义结构模型：shiyuanstone2014年10月8日先定义结构模型，应用时通过“schema”属性设置所使用的结构模型的名称。2.3.5.4安全认证模型securitySchemes假如一个API需要OAuth安全认证，这个API的所有资源和方法的定义必须包含“access_token”查询参数。针对这种场景可以定义重用属性，让其他资源或方shiyuanstone2014年10月8日法通过继承的方式来获取属性的设置。定义方法时通过“securedBy”是指定安全认证模型，“securedBy”属性值为集合类型。3RAML支持工具3.1RAML资源官方网站：规范文档：设计器：年10月8日解析器：JS解析器：，生成浏览器可访问的API文档java解析器：。基于该解析器我们可以开发出生成API文档，、API调用客户端代码以及将API定义导入到服务中心的功能。