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

一、前言

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

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

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

所以，決定在此基礎上，再進行一些最佳化

二、1. 分地區展示

2.介面參數說明

   

3.授權參數統一傳入 token

   

4.介面查詢

5.介面開發狀態

   

三、關鍵實現1.項目屬性設定產生xml文檔檔案

   

2.修改SwaggerConfig.cs檔案

   

3. 修改WebApiConfig.cs檔案，配置路由

   

4.分地區篩選關鍵邏輯

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

 

   

四、Demo源碼地址

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

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

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

五、總結

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

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

六、參考

• Webapi文檔描述-swagger最佳化