swagger

隨着互聯網技術的發展，如今的網站架構基本都由原來的後端渲染，變成了：前端渲染、前後端分離的形態，並且前端技術和後端技術在各自的道路上越走越遠。
前端和後端的惟一聯繫，變成了API接口；API文檔變成了先後端開發人員聯繫的紐帶，變得愈來愈重要，swagger就是一款讓你更好的書寫API文檔的框架。
其餘API文檔工具

沒有API文檔工具以前，你們都是手寫API文檔的，在什麼地方書寫的都有，有在confluence上寫的，有在對應的項目目錄下readme.md上寫的，每一個公司都有每一個公司的玩法，無所謂好壞。

書寫API文檔的工具備不少，可是能稱之爲「框架」的，估計也只有swagger了。
在此先介紹一款其餘的API文檔工具，叫rap，這玩意兒用一句話就能歸納：解放生產力，代替手寫API的web工具。
RAP寫起來確實比手寫文檔要快，看看圖就知道：
能夠選擇某個項目，寫針對某個項目的API

請看，能夠填寫請求和相應的字段

還能夠選擇字段對應的類型

相似的API文檔工具網上還有不少，可是能拿上臺面的，很少。RAP是由阿里開發的，整個阿里都在用，還不錯。github地址爲：https://github.com/thx/RAP
固然咯，rap不可能只有線上版本，確定能夠部署到私服上。
https://github.com/thx/RAP/wiki/deploy_manual_cn
swagger

rap挺好的，可是和swagger比起來有點輕量。
先看看swagger的生態使用圖：

其中，紅顏色的是swaggger官網方推薦的。

下面再細看看swagger的生態的具體內容：
swagger-ui

這玩意兒從名字就能看出來，用來顯示API文檔的。和rap不一樣的是，它不能夠編輯。

點擊某個詳細API的能夠試。

swagger-editor

就是一個在線編輯文檔說明文件（swagger.json或swagger.yaml文件）的工具，以方便生態中的其餘小工具（swagger-ui）等使用。
左邊編輯，右邊立馬就顯示出編輯內容來。

編輯swagger說明文件使用的是yaml語法具體的內容能夠去官網查看。
各類語言版本的根據annotation或者註釋生成swagger說明文檔的工具

目前最流行的作法，就是在代碼註釋中寫上swagger相關的註釋，而後，利用小工具生成swagger.json或者swagger.yaml文件。

目前官方沒有推出。github上各類語言各類框架各類有，能夠本身搜吧搜吧，這裏只說一個php相關的。
swagger-php :https://github.com/zircote/swagger-php
swagger-validator

這個小工具是用來校驗生成的文檔說明文件是否符合語法規定的。用法很是簡單，只需url地址欄，根路徑下加上一個參數url，參數內容是放swagger說明文件的地址。便可校驗。
例如：

docker hub地址爲：https://hub.docker.com/r/swaggerapi/swagger-validator/
能夠pull下鏡像來本身玩玩。
swagger-codegen

代碼生成器，腳手架。能夠根據swagger.json或者swagger.yml文件生成指定的計算機語言指定框架的代碼。
有必定用處，Java系用的挺多。工業上應該不咋用。
mock server

這個目前尚未找到很合適的mock工具，包括rap也好，其餘API文檔工具也好，都作的不夠完善，大多就是根聽說明文件，例如swagger.json等生成一些死的靜態的mock數據，不可以根據限定條件：例如「只能是數字，必傳」等作出合理的迴應。
 

其餘相關參考：

https://blog.csdn.net/sanyaoxu_2/article/details/80555328