使用Swagger 搭建高可讀性ASP.Net WebApi文檔

1、前言

在最近一個商城項目中，使用WebApi搭建API項目。但開發過程當中，先後端工程師對於溝通接口的使用，是很是耗時的。以前也有用過Swagger構建WebApi文檔，可是API文檔的可讀性並不高。尤爲是沒有傳入參數和傳出結果的說明，致使開發人員溝通困難。在園子裏看到一篇關於對Swagger優化的文章，有很大的改進。解決了傳入參數，API分區域篩選等問題， 很是感謝博主簡玄冰。

不過實踐以後，發現還有些問題未解決:

1. 接口返回的對象，沒有漢化說明
2. 接口受權參數(token)未統一傳入

因此，決定在此基礎上，再進行一些優化

2、效果圖

1. 分區域展現

2.接口參數說明

   

3.受權參數統一傳入 token

   

4.接口查詢

5.接口開發狀態

   

3、關鍵實現

1.項目屬性設置生成xml文檔文件

   

2.修改SwaggerConfig.cs文件

   

3. 修改WebApiConfig.cs文件，配置路由

   

4.分區域篩選關鍵邏輯

 須要注意: 實現邏輯與命名空間的分割符. 有很大關係，具體請查看文件SwaggerAreasSupportDocumentFilter.cs

 

   

4、Demo源碼地址

 Github: https://github.com/yinboxie/Swagger-Demo.git

 下載demo源碼後，若是發現不能自動下載nuget依賴包，請執行命令Update-Package -ProjectName 'swagger.demo.api' -Reinstall

 啓動項目以後，訪問地址http://localhost:11008/apis/index

5、總結

Swashbuckle 源碼是沒有註釋說明，比較難以閱讀。我也只是在大神簡玄冰的基礎上，修改了幾處Swashbuckle 源碼。

改動以後的Swashbuckle 源碼 Github: https://github.com/yinboxie/SwashbuckleEx.git

6、參考

• Webapi文檔描述-swagger優化