RAML是什么呢?

下面這段話摘自于網(wǎng)絡(luò)

RAML的全稱是RESTful API建模語言，這是一種基于YAML格式的新規(guī)范，因此機(jī)器與人類都能夠輕易地理解其中的內(nèi)容。但RAML的目的不僅僅在于創(chuàng)建更易于理解的規(guī)范（你可以將這一工作指派給文檔團(tuán)隊(duì)，他們會(huì)做得更好）而已。RAML的設(shè)計(jì)者Uri Sarid希望使用者能夠打破固有的思維，在開始編寫代碼之前以一種全新的方式對(duì)API進(jìn)行建模。

它的官網(wǎng)是:

http://raml.org/

雖然目前國(guó)內(nèi)沒有太多這方面的資料,國(guó)外也是不溫不火的,但是圍繞著raml已經(jīng)建立起了一個(gè)小的生態(tài),涵蓋了API的全部生命周期,從設(shè)計(jì)到構(gòu)建,從測(cè)試到文檔

raml是和具體開發(fā)語言無關(guān)的,但是需要依賴具體的第三方工具來提供相應(yīng)的服務(wù),目前對(duì)于nodejs,python,java,php等語言均支持的不錯(cuò),本人以nodejs為例進(jìn)行學(xué)習(xí).

先看一下語法

#%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是不是很像?而且看起來很簡(jiǎn)單?

接下來介紹一下他的編輯器

• API-wordkbench
• API-Design

API-workbench是基于atom的插件,支持raml語法和實(shí)時(shí)預(yù)覽

http://apiworkbench.com/

API-Design是一個(gè)基于nodejs的web編輯器,需要自己部署服務(wù)端

https://github.com/mulesoft/api-designer

而我選擇了API-workbench

API-workbench

圖中為示例代碼,可以在下面的url中拿到

http://static-anypoint-mulesoft-com.s3.amazonaws.com/API_examples_notebooks/raml-design3.html

生成mock服務(wù)

這里用到的工具是Osprey Mock Service:

https://github.com/mulesoft-labs/osprey-mock-service

使用方法

npm install -g osprey-mock-service
osprey-mock-service -f api.raml -p 8000

這里api.raml是上一步中生成的raml文件
接下來訪問 http://localhost:8000/cases,就有模擬的輸出了

實(shí)現(xiàn)API

接下來本應(yīng)該是編碼實(shí)現(xiàn)的,但是為了快速感受raml的特點(diǎn),此步驟略過,由mock服務(wù)代替

測(cè)試

測(cè)試用的工具有多重選擇,選擇了相對(duì)比較流行的Abao工具,工具可以在下面找到

https://github.com/cybertk/abao/

使用方法

npm install -g abao
abao api.yaml  --server http://localhost:8080

如果api.yaml中提供了baseUrl屬性的話,也可以不指定--server屬性

微信截圖_20170211174744.png

免責(zé)聲明

本文為初次學(xué)習(xí)筆記,對(duì)于多處均略過,如果有不對(duì)的地方,請(qǐng)留言指正.