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
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章