api文檔設計工具是用來描述和輔助API開發的。
一、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文件遠程讀取解析
二、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生成的文檔
三、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