隨著互聯網技術的發展，現在的網站架構基本都由原來的後端渲染，變成了：前端渲染、先後端分離的形態，而且前端技術和後端技術在各自的道路上越走越遠。 前端和後端的唯一聯繫，變成了API介面；API文檔變成了前後端開發人員聯繫的紐帶，變得越來越重要，swagger就是一款讓你更好的書寫API文檔的框架。 其 ...
隨著互聯網技術的發展，現在的網站架構基本都由原來的後端渲染，變成了：前端渲染、先後端分離的形態，而且前端技術和後端技術在各自的道路上越走越遠。
前端和後端的唯一聯繫，變成了API介面；API文檔變成了前後端開發人員聯繫的紐帶，變得越來越重要，swagger就是一款讓你更好的書寫API文檔的框架。
其他API文檔工具
沒有API文檔工具之前，大家都是手寫API文檔的，在什麼地方書寫的都有，有在confluence上寫的，有在對應的項目目錄下readme.md上寫的，每個公司都有每個公司的玩法，無所謂好壞。
書寫API文檔的工具有很多，但是能稱之為“框架”的，估計也只有swagger了。
在此先介紹一款其他的API文檔工具，叫rap，這玩意兒用一句話就能概括：解放生產力，代替手寫API的web工具。
RAP寫起來確實比手寫文檔要快， 可以選擇某個項目，寫針對某個項目的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不同的是，它不可以編輯。
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數據，不能夠根據限定條件：例如“只能是數字，必傳”等做出合理的回應。
C# 在webapi項目中配置Swagger
1、安裝包 Swashbuckle
會自動生成 SwaggerConfig.cs文件
2、右鍵項目屬性—>生成—>勾選XML文檔文件
eg bin\WebApi.xml 【若對api寫了註釋，併在swagger中 開啟了，則會自動生成一些說明節點】
3、運行 eg：http://localhost:2146/swagger
4、發現，安裝完成後，寫註釋並沒有在swagger頁面上面增加，所以我們現在開開啟註釋
在SwaggerConfig類中，EnableSwagger的時候添加下麵XML解析（預設是有的，只是註釋掉了）
c.IncludeXmlComments(GetXmlCommentsPath());
並添加方法 即可
/// <summary> /// 添加XML解析 /// </summary> /// <returns></returns> private static string GetXmlCommentsPath() { return string.Format("{0}/bin/WebApi.XML", System.AppDomain.CurrentDomain.BaseDirectory); }View Code
xml文檔中也會自動寫入註釋
5、調試
註意參數是字元串時需要帶雙引號""，、
更多參考：
https://www.cnblogs.com/lhbshg/p/8711604.html
