Webapi文檔描述-swagger優化

一、前言

最近做的項目使用

WebApi

，采取前後端分離的方式，背景提供

API

接口給前端開發人員。這個過程中遇到一個問題背景開發人員怎麼提供接口說明文檔給前端開發人員，最初打算使用

word

、

Xmind思維導圖

方式進行交流，實際操作中卻很少動手去寫。為了解決這個問題，特意在部落格園搜尋了一下

api

接口文檔生成的文章，引起我注意的有以下兩種方案。

• 微軟自帶的

  Microsoft.AspNet.WebApi.HelpPage

• Swagger（絲襪哥）

但是在使用過程中微軟自帶的沒有

Swagger

直覺，是以采用了第二種方案

Swagger

。

二、問題

在使用swagger的過程中，産生了一些小問題，例如：

漢化

查詢

控制器備注

在部落格園當中找到了相關的解決方式，但是漢化、控制器備注會産生二次請求的問題，尤其在接口比較多的情況下，還是比較慢的。是以産生了修改

swagger-ui

和

Swashbuckle

源碼的念頭。

三、效果圖

3.1 漢化效果

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

3.3 查詢

四、如何使用

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>
           

五、源碼位址

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

六、總結

修改

Swashbuckle

源碼過程中，踩的坑還是比較多的，這個後續開一篇文章進行說明實作上述的功能。

有了漢化、控制器注釋、接口數量統計、查詢，加快的前後端開發的對接。

七、參考

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