Webapi文檔描述-swagger優化

1、前言

最近作的項目使用WebApi，採起先後端分離的方式，後臺提供API接口給前端開發人員。這個過程當中遇到一個問題後臺開發人員怎麼提供接口說明文檔給前端開發人員，最初打算使用word、Xmind思惟導圖方式進行交流，實際操做中卻不多動手去寫。爲了解決這個問題，特地在博客園搜索了一下api接口文檔生成的文章，引發我注意的有如下兩種方案。

• 微軟自帶的Microsoft.AspNet.WebApi.HelpPage
• Swagger（絲襪哥）

可是在使用過程當中微軟自帶的沒有Swagger直觀，所以採用了第二種方案Swagger。

2、問題

在使用swagger的過程當中，產生了一些小問題，例如：漢化、查詢、控制器備註。
在博客園當中找到了相關的解決方式，可是漢化、控制器備註會產生二次請求的問題，尤爲在接口比較多的狀況下，仍是比較慢的。所以產生了修改swagger-ui和Swashbuckle源碼的念頭。

3、效果圖

3.1 漢化效果

3.2 控制器註釋以及接口數量統計

3.3 查詢

4、如何使用

4.1 建立Webapi項目解決方案

4.2 引用SwashbuckleEx nuget包

SwashbuckleEx和SwashbuckleEx.Core這兩個包

4.3 添加接口註釋

完成上面2部運行項目，能夠看到接口描述已經生成，瀏覽地址http://xxxx/swagger。可是沒有接口的註釋，下面添加接口註釋。

4.3.1 項目屬性->勾選生成xml文檔文件

注：若是實體與Api庫分開，那麼須要在實體庫也勾選上生成xml文件，並設置文件名稱（默認名稱便可）。

4.3.2 修改SwaggerConfig.cs文件

c.SingleApiVersion("v1", "xxx");
c.IncludeXmlComments(string.Format("{0}/bin/xxx.Api.XML", AppDomain.CurrentDomain.BaseDirectory));

給接口添加註釋，便可看到參數與方法描述了。

4.3.3 配置Web.config文件

有園友提出使用Nuget包後，展現是空的，所以看了下，須要配置一下如下的內容便可。

<system.webServer>
    <modules runAllManagedModulesForAllRequests="true">
        <remove name="WebDAVModule" />
    </modules>
</system.webServer>

5、源碼地址

Github：https://github.com/jianxuanbing/SwashbuckleEx.git

6、總結

修改Swashbuckle源碼過程當中，踩的坑仍是比較多的，這個後續開一篇文章進行說明實現上述的功能。
有了漢化、控制器註釋、接口數量統計、查詢，加快的先後端開發的對接。

7、參考

• ASP.NET WebApi 文檔Swagger中度優化
• ASP.NET WebApi 文檔Swagger深度優化