前言
這是我第一次寫raml猾封，一開始雜亂無章沒有從宏觀角度去思考，什么都想加進(jìn)去抛丽，導(dǎo)致越來越復(fù)雜谤职，后來在李老師指導(dǎo)下抽絲剝繭，才看清楚raml真正的意義亿鲜。
摘要
RAML 是一種基于HTTP-API的定義語言. 體現(xiàn)了所有對象傳輸狀態(tài)的原則 . RAML基于YAML ,依靠標(biāo)準(zhǔn)和最佳實踐從而編寫更高質(zhì)量的API . 生成全面的用戶文檔 .
RAML通過一個格式來提供規(guī)范的接口.作為API提供者和使用者之間的合約.用戶可使用文檔實現(xiàn)客戶端和服務(wù)器的交互.
組織結(jié)構(gòu)
- 基本信息 解釋了如何描述核心API的方面,如它的名稱允蜈、標(biāo)題、位置(URI)和違約蒿柳。
- 數(shù)據(jù)類型 描述了一種通過簡化模型API數(shù)據(jù)類型系統(tǒng),也包括JSON和XML模式饶套。
- 資源 描述了如何指定一個API的資源和嵌套的資源,以及在任何URI URI參數(shù)模板，所有一類事物從宏觀講都是一類垒探，同一類中事物具有不同的性質(zhì)妓蛮，但是raml不考慮性質(zhì)uri指向的就是資源，所有的操作方法只是對uri所指向的資源的操作圾叼，和uri本身并沒有關(guān)系蛤克。
- 方法 描述了如何指定API的資源上的method,以及他們的請求頭,查詢參數(shù)和請求，一般的有四個主要的method夷蚊，post添加构挤，get查詢，put更新惕鼓，delete刪除筋现。
- 響應(yīng) 描述API規(guī)范的反應(yīng),包括狀態(tài)碼、媒體類型,響應(yīng)頭和響應(yīng)，一般有200-請求成功矾飞，404- 請求的資源不存在彻犁，500-服務(wù)器內(nèi)部錯誤，凰慈。
- 資源類型和特征 描述可選機制使用RAML資源類型和特征描述資源,避免不必要的重復(fù)在一個API的定義和促進(jìn)一致性和重用，在對同一路徑下的資源進(jìn)行操作可以合并操作驼鹅，對于get和post要理解輸入什么微谓，輸出什么。
- 安全 描述了機制中可用RAML指定一個API的安全方案输钩。
-
注釋 描述了擴(kuò)展機制RAML規(guī)范通過定義強類型的注釋和應(yīng)用規(guī)范豺型。
Includes,Libraries 覆蓋以及擴(kuò)展 描述了一個API的定義可能是由外部化定義文件,如何打包成庫集合的定義,如何分離和覆蓋層的元數(shù)據(jù)的RAML文檔,以及一個API規(guī)范與附加功能可以擴(kuò)展。
出現(xiàn)的問題以及解決方法
1.首先拿到需求時买乃， 沒有仔細(xì)對需求分析姻氨，需求中的三個接口，個人卻又加入太多的個人定義剪验，直接導(dǎo)致后面越來越復(fù)雜無法進(jìn)行下去肴焊，其實首先拿到需求應(yīng)該是做減法，先從滿足最簡單功能的開始功戚，設(shè)計raml的初衷就是化繁為簡娶眷，如同一張總施工圖，指導(dǎo)每一步啸臀，但不過問每一步具體實現(xiàn)届宠。
2.對資源定義理解不夠深刻，人為給資源進(jìn)行分類乘粒，沒有對整體進(jìn)行把握豌注，比如我和plant都是同一個屬性，當(dāng)定義了plant是研發(fā)部領(lǐng)導(dǎo)的時候才有上下級關(guān)系灯萍，查找我只要在plant下面進(jìn)行檢索轧铁。
3.uri理解的偏差，raml里面包含,uri和method竟稳，uri就好比指的是資源的路徑属桦，method才是對資源操作的方法，這個理解是最重要的他爸，之前我定義的/inputnode聂宾，/findnode，/allnode诊笤，相當(dāng)于在三個路徑里面對三個文件進(jìn)行操作系谐，只要理解到uri是路徑，需求里所有的操作都是指向一個路徑操作。
4.需求中輸入節(jié)點返回節(jié)點及其子孫節(jié)點纪他，/api/Nodes/{valuename},這里面valuename就是要查詢的節(jié)點
/api/Nodes:
/{valuename}:
get:
description: Get Total Value Xml information
displayName: ValueNodeXml
responses:
200:
body:
application/xml:
type: HierarchyNode
404:
500:
5.http主要有四種方法鄙煤，post添加，get查找茶袒，put更新梯刚，delete刪除，在uri路徑上進(jìn)行操作方法選擇上由于之前理解的偏差出錯
6.在現(xiàn)有的需求里post不會有404薪寓，在get里面才有404亡资，但是也要看實際情況，例如
7.post是輸入body里是輸入的資源向叉，存儲成功返回200锥腻，服務(wù)器錯誤返回500
post:
description: Obtain storage resources
displayName: StorageResource
body:
application/json:
type: HierarchyPath
responses:
200:
500:
總結(jié)反思
我是半路轉(zhuǎn)行培訓(xùn)學(xué)的java，計算機相關(guān)的基礎(chǔ)知識知道甚少母谎，數(shù)據(jù)結(jié)構(gòu)一知半解瘦黑，培訓(xùn)后總是把學(xué)到的東西作為一種標(biāo)準(zhǔn)來對比新接觸的東西，這是一件很可怕的事情奇唤，在編程的行業(yè)的沒有什么是一成不變的標(biāo)準(zhǔn)幸斥，時刻都在變換的行業(yè)里，就好比自己是一個小杯子裝滿了各個地方收集來水冻记，以至于現(xiàn)在再也裝不下更多睡毒，只有放空自己，才能裝得下更多的東西冗栗。
