RAML文件書寫說明
文檔基本組成部分
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