RAML是什么呢?
下面這段話(huà)摘自于網(wǎng)絡(luò)
RAML的全稱(chēng)是RESTful API建模語(yǔ)言，這是一種基于YAML格式的新規(guī)范趁曼，因此機(jī)器與人類(lèi)都能夠輕易地理解其中的內(nèi)容。但RAML的目的不僅僅在于創(chuàng)建更易于理解的規(guī)范（你可以將這一工作指派給文檔團(tuán)隊(duì)，他們會(huì)做得更好）而已。RAML的設(shè)計(jì)者Uri Sarid希望使用者能夠打破固有的思維最域，在開(kāi)始編寫(xiě)代碼之前以一種全新的方式對(duì)API進(jìn)行建模。
它的官網(wǎng)是:
雖然目前國(guó)內(nèi)沒(méi)有太多這方面的資料,國(guó)外也是不溫不火的,但是圍繞著raml已經(jīng)建立起了一個(gè)小的生態(tài),涵蓋了API的全部生命周期,從設(shè)計(jì)到構(gòu)建,從測(cè)試到文檔
raml是和具體開(kāi)發(fā)語(yǔ)言無(wú)關(guān)的,但是需要依賴(lài)具體的第三方工具來(lái)提供相應(yīng)的服務(wù),目前對(duì)于nodejs,python,java,php等語(yǔ)言均支持的不錯(cuò),本人以nodejs為例進(jìn)行學(xué)習(xí).
先看一下語(yǔ)法
#%RAML 0.8
title: Remote Medicine Example API
mediaType: application/json
/cases:
description: The urgent cases created by the remote medicine partner
get:
description: Get a list of cases
queryParameters:
startFrom:
type: number
description: The number of the first question, where 0 means latest
default: 0
numberToReturn:
type: number
description: How many questions to return
default: 5
responses:
200:
body:
example: |
{
"totalNumber": 3781,
"cases":
[
{
"id": "c68732",
"overview": "The patient just collapsed",
"location": "Oro Valley",
"created": "Sat, 24 May 2014 23:18:01 GMT"
},
{
"id": "c98729",
"overview": "The patient felt severe headaches and saw flashes",
"location": "Picacho Peak",
"created": "Fri, 25 Apr 2014 04:34:00 GMT"
}
]
}
和yaml是不是很像?而且看起來(lái)很簡(jiǎn)單?
接下來(lái)介紹一下他的編輯器
- API-wordkbench
- API-Design
API-workbench是基于atom的插件,支持raml語(yǔ)法和實(shí)時(shí)預(yù)覽
API-Design是一個(gè)基于nodejs的web編輯器,需要自己部署服務(wù)端
而我選擇了API-workbench
圖中為示例代碼,可以在下面的url中拿到
http://static-anypoint-mulesoft-com.s3.amazonaws.com/API_examples_notebooks/raml-design3.html
生成mock服務(wù)
這里用到的工具是Osprey Mock Service:
使用方法
npm install -g osprey-mock-service
osprey-mock-service -f api.raml -p 8000
這里api.raml是上一步中生成的raml文件
接下來(lái)訪(fǎng)問(wèn) http://localhost:8000/cases,就有模擬的輸出了
實(shí)現(xiàn)API
接下來(lái)本應(yīng)該是編碼實(shí)現(xiàn)的,但是為了快速感受raml的特點(diǎn),此步驟略過(guò),由mock服務(wù)代替
測(cè)試
測(cè)試用的工具有多重選擇,選擇了相對(duì)比較流行的Abao工具,工具可以在下面找到
使用方法
npm install -g abao
abao api.yaml --server http://localhost:8080
如果api.yaml中提供了baseUrl屬性的話(huà),也可以不指定--server屬性
免責(zé)聲明
本文為初次學(xué)習(xí)筆記,對(duì)于多處均略過(guò),如果有不對(duì)的地方,請(qǐng)留言指正.
