api文檔設計工具：RAML、Swagger

api文檔設計工具是用來描述和輔助API開發的。

1、RAML

https://raml.org/　　https://wenku.baidu.com/view/9523238d5ef7ba0d4b733b16.html###

RAML(RESTful API Modeling Language 即 RESTful API 建模語言)是對 RESTful API的一種簡單和直接的描述。它是一種讓人們易於閱讀而且能讓機器對特定的文檔能解析的語言。RAML 是基於 YAML,能幫助設計 RESTful API 和鼓勵對API的發掘和重用,依靠標準和最佳實踐從而編寫更高質量的API。經過RAML定義,由於機器可以看得懂,因此能夠衍生出一些附加的功能服務,像是解析並自動生成對應的客戶端調用代碼、服務端代碼 結構, API說明文檔。

上面這段引用自網絡，這是我見到的對RAML最清晰的描述了。RAML本質上能夠理解爲一種文檔的書寫格式，這種格式是特別針對API的，就像Markdown是針對HTML的同樣。而且RAML也一樣具有了像Markdown那樣的可讀性，即便是看RAML源碼也能很快明白其意圖。另外基於RAML語言，有很多輔助API開發的工具，這裏特別推薦一下raml2html與api-console，它們均可以將raml源文件轉換成精美的doc文檔頁面，其中raml2html轉換結果是靜態的，api-console則能夠生產可直接交互的api文檔頁面，有些相似後面要說的Swagger。

raml2html輸出的文檔

api-console生成的結果，能夠直接在線編輯RAML後解析，也能夠給出RAML文件遠程讀取解析

 

 

2、Swagger

https://mp.weixin.qq.com/s?__biz=MzAwNDYwNzU2MQ==&mid=400011200&idx=1&sn=51f132551bcd5a7d2aabb56047ba6f07&scene=21##

Swagger與RAML相比，RAML解決的問題是設計階段的問題，而Swagger則是側重解決現有API的文檔問題，它們最大的不一樣是RAML須要單獨維護一套文檔，而Swagger則是經過一套反射機制從代碼中生成文檔，而且藉助ajax能夠直接在文檔中對API進行交互。由於代碼與文檔是捆綁的因此在迭代代碼的時候，就能方便的將文檔也更新了。不會出現隨着項目推移代碼與文檔不匹配的問題。另外Swagger是基於JSON進行文檔定義的。

Swagger生成的文檔

 

 

3、API Blueprint

API Blueprint是使用Markdown來定義API的，Markdown相比前面兩個RAML、JSON門檻又下降了一大截。同時API Blueprint與前面的Swagger、RAML同樣也能提供可視化的文檔界面與Mock Server的功能。不過其Mock能力比較弱。

 

工具就是這樣的，具體到使用還得看你的應用場景，對於我的開發，小項目我比較喜歡Swagger，代碼與文檔一同維護省太多事兒了，但對於團隊開發，使用RAML這種建模語言進行設計與溝通是不錯的選擇，而且RAML的Mock和文檔能力也不弱，麻煩就在於增長維護成本，不過既然都團隊了這個也就不是什麼問題了。至於API Blueprint說實話沒怎麼用過，不過感受用Markdown挺美好的。

參考引用

• https://www.cnblogs.com/softidea/p/5728952.html