Swagger

Swagger與RAML相比，RAML解決的問題是設計階段的問題，而Swagger則是側重解決現有API的文件問題，它們最大的不同是RAML需要單獨維護一套文件，而Swagger則是通過一套反射機制從程式碼中生成文件，並且藉助ajax可以直接在文件中對API進行互動。因為程式碼與文件是捆綁的所以在迭代程式碼的時候，就能方便的將文件也更新了。不會出現隨著專案推移程式碼與文件不匹配的問題。另外Swagger是基於JSON進行文件定義的。

python flask swagger 外掛：

https://github.com/rantav/flask-restful-swagger

Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。其將維護介面文件的工作，與維護程式碼相結合，使得二者可以齊頭並進，隨著程式碼檔案的更新，文件也得到了更新。

RAML

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

raml2html輸出的文件

api-console生成的結果，可以直接線上編輯RAML後解析，也可以給出RAML檔案遠端讀取解析

API Blueprint

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