RAML文件书写规则笔记

RAML文件书写说明

RAML1.0官方文档地址

文档基本组成部分

raml文件必须以#%RAML1.0开头

• 基本信息
• 数据类型
• 资源
• 请求方法
• 响应体
• 资源类型和特征定义模块
• 安全模块
• 引用、库、重写和扩展
  如下图所示：
  

基本信息

根节点下的基本属性

名称后跟?表示该属性非必填，没有?表示该属性必填

名称	描述
title	API文档标题
description?	API文档描述
version?	API版本信息
baseUri?	全部资源的基础URI
baseUriParameters?	在基础URI中使用的参数
protocols?	API支持的协议
mediaType?	API支持的默认媒体类型
documentation?	API的额外总体文档
schemas?	RAML0.8中的属性，在1.0中已弃用，等价于RAML1.0中的types
types?	定义API中使用的数据类型
traits?	定义API中使用的公共特性
resourceTypes?	定义API中使用的资源类型
annontationTypes?	定义API中使用的注释类型
securitySchemas?	定义API中使用的安全方案
securityBy?	应用于API中每个资源和方法的安全方案
uses?	导入外部库在当前API中使用
/?	API资源URI

数据类型

Properties下的属性

属性	含义	默认值	备注
type?	属性值类型	string
required?	是否必填	true
maxLength?	最大长度	2147483647	只适用于类型为number或integer的参数
minLength?	最小长度	0	只适用于类型为number或integer的参数
pattern?	正则表达式
format?	值格式		该值必须是以下类型之一:int32, int64, int, long, float, double, int16, int8
multipleOf?			如果实例除以关键字的值是整数，则数值实例对“multipleOf”有效
default?	默认值
enum?	枚举
displayName?	API文档显示的名称
examples?	示例（复数）
example?	示例（单数）
description?	属性描述

Properties下属性中type的取值类型

类型	含义	备注	示例
string	字符	当properties下的属性字段不指定type时，则默认值为string
number	数字
integer	整数
boolean	布尔
array	集合
file	文件
fileTypes	文件类型	当type=file时子属性
object	对象	当type为空时，默认值为object
date-only	日期	RFC3339的“完整”标记，即yyyy-mm-dd。不支持时间或时间区域偏移表示法	2015-05-23
time-only	时间	RFC3339的“部分时间”符号，即hh:mm:ss。不支持时间或时间区域偏移表示法	12:30:00
datetime	日期时间	如果格式被省略或设置为RFC3399，使用RFC3399的“日期-时间”符号;如果格式设置为RFC2616，则使用RFC2616中定义的格式	RFC3399格式： 2015-05-23T12:30:00.090Z RFC2616格式： Sun, 28 Feb 2016 16:41:41 GMT
datetime-only	数字	只有日期和只有时间，加上一个“T”分隔符，即yyyy-mm-ddThh:mm:ss。不支持时区域偏移表示法	2015-07-04T21:00:00
nil	只允许值为空	只允许值为空，不允许赋值
any	任何类型	当节点不包含properties, type, or schema时，则默认值为any

types

types的作用是在API文件中声明及约束公共的数据类型，可以引入外部定义好的types文件，也可以在API描述文档（RAML）中直接编写。示例如下：

# 完整的写法如下：（当然这里只列出了一部分属性，全部属性参见上一章节的表格）
types:
  User:
    properties: 
      name:
        type: string
        required: true
        description: 姓名
        example: 张三
      address:
        type: string
        required: false
        description: 地址
        example: 太阳系地球村
      age:
        type: number
        required: true
        description: 年龄
        example: 18
# 简写的写法如下：
types:
  User:
    type: object
    properties:
      name: string
      address?: string
      age: number

RAML文件中的数据类型是可以继承的，如下:

types:
  User:
    type: object
    properties:
      name: string
      address?: string
      age: number
  Student:
    type: User
    properties: 
      studentNumber: number
      classes: string
      schoolName: string

Student就在User的三个属性的基础上，新增加了三个非空属性

traits

traits就是在API中描述了一些公共的特性（比方说一些分页的参数、一些公共的参数信息），将其抽出来，当你在需要使用的时候，通过is即可引用。如下：

types:
  User:
    properties: 
      name:
        type: string
        required: true
        description: 姓名
        example: 张三
      address:
        type: string
        required: false
        description: 地址
        example: 太阳系地球村
      age:
        type: number
        required: true
        description: 年龄
        example: 18
  Student:
    type: User
    properties: 
      studentNumber: number
      classes: string
      schoolName: string
      
traits: 
  orderable:
    queryParameters: 
      orderBy?: string
      sortBy?: string
  pageable:
    queryParameters: 
      startPage?: number
      rowSize?: number
      currPage?: number
  oauth2Param:
    headers: 
      access_token: string
      client_id: string
      timestamp: string
        
/Students:
  /{studentNumber}: 
    get:
      is:
        - oauth2Param
        - orderable
        - pageable
      queryParameters:
        name?: string
      headers:
        custom_token: string
          type: string
          description: |
          自定义Header参数
          example: SWED-1234 # single scalar example
      responses:
        201:
          body:
            type: Student

在外部单独定义资源文件

相信你也看到不少include的使用，但是怎么在外部定义一个资源文件，再怎么引入到我们APi文件中来呢，这里就先贴一个官方的OAuth2.0的外部资源文件，然后我们再自定义一个我们自己的资源文件，很快你就知道怎么使用了。
下面是一个API Design上提供的标准securitySchemes外部资源文件

#%RAML 1.0 SecurityScheme
description: |
  Dropbox supports OAuth 2.0 for authenticating all API requests.
type: OAuth 2.0
describedBy:
  headers:
    X-SOA-CLIENT-ID:
      description: |
          Used to send a valid OAuth 2 access token. Do not use
          with the "client_id" query string parameter.
      type: string
    X-SOA-ACCESS-TOKEN:
      description: |
          Used to send a valid OAuth 2 access token. Do not use
          with the "access_token" query string parameter.
      type: string
  queryParameters:
    access_token:
      description: |
          Used to send a valid OAuth 2 access token. Do not use with
          the "Authorization" header.
      type: string
  responses:
    401:
      description: |
          Bad or expired token. This can happen if the user or Dropbox
          revoked or expired an access token. To fix, re-authenticate
          the user.
    403:
      description: |
          Bad OAuth request (wrong consumer key, bad nonce, expired
          timestamp...). Unfortunately, re-authenticating the user won't help here.
settings:
  authorizationUri: https://www.dropbox.com/1/oauth2/authorize
  accessTokenUri: https://api.dropbox.com/1/oauth2/token
  authorizationGrants: [ authorization_code, implicit, 'urn:ietf:params:oauth:grant-type:saml2-bearer' ]

下面我们来自定义一个我们自己的资源文件，如下所示：

#%RAML 1.0 
type: custom
describedBy:
  headers:
    first_name:
      description: 测试属性1
      type: string
  queryParameters:
    access_token:
      description: 测试属性2
      type: string
  responses:
    666:
      description: 六六大顺
    888:
      description: |
          恭喜发财

通过两者的比较，应该不难发现区别吧，下面我开始引用这里定义的两个资源文件

include

include在API中表示引入一个外部资源文件，外部资源路径用相对路径，绝对路径是不行的哦，如下所示：

#%RAML 1.0
title: Salesforce Chatter REST API
version: v1.0
protocols: [ HTTP, HTTPS ]
mediaType: application/json
baseUri: https://127.0.0.1:8080/services/data/{bucketName}/chatter
baseUriParameters:
  bucketName:
    description: The name of the bucket
types:
  User:
    properties: 
      name:
        type: string
        required: true
        description: 姓名
        example: 张三
      address:
        type: string
        required: false
        description: 地址
        example: 太阳系地球村
      age:
        type: number
        required: true
        description: 年龄
        example: 18
  Student:
    type: User
    properties: 
      studentNumber: number
      classes: string
      schoolName: string
      
traits: 
  orderable:
    queryParameters: 
      orderBy?: string
      sortBy?: string
  pageable:
    queryParameters: 
      startPage?: number
      rowSize?: number
      currPage?: number
  oauth2Param:
    headers: 
      access_token: string
      client_id: string
      timestamp: string
securitySchemes:
  oauth_2_0: !include ./security_schemes/oauth_2_0.raml
  custom_scheme: !include ./security_schemes/custom.raml
        
/Students:
  /{studentNumber}: 
    get:
      is:
        - oauth2Param
        - orderable
        - pageable
      securedBy: 
        - oauth_2_0
        - custom_scheme
      queryParameters:
        name?: string
      headers:
        custom_token: string
          type: string
          description: |
          自定义Header参数
          example: SWED-1234 # single scalar example
      responses:
        201:
          body:
            type: Student