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 |
属性 | 含义 | 默认值 | 备注 |
---|---|---|---|
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? | 属性描述 |
类型 | 含义 | 备注 | 示例 |
---|---|---|---|
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的作用是在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就是在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在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