使用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: https://github.com/yinboxie/Swagger-Demo.git

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

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

五、總結

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

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

六、參考

• Webapi文檔描述-swagger優化