WebApi使用swagger ui自動生成介面文檔

之前就寫到。最近正在使用webapi。這裡介紹一個實用的東西swageer ui
現在開發都是前後端分開。我們這裡是給前端提供api。有時候對於一個api的描述，並不想專門寫一份文檔。很浪費時間。
swagger ui就是一個能整合到項目中讓api的註釋能夠生成到一個網頁上。能簡單測試和給前端看。
開懟吧。

Step.1 Nuget安裝
打開你的Nuget console，Install-Package Swashbuckle（要選擇哪個項目）

ps.其實第一步安裝完了，你什麼不用做。運行起來，網址進入/swagger/ui/index就能看到你的那些api了（不帶註釋），不過沒達到我們的預期效果——將註釋自動生成到文檔上。so，繼續往下看

Step.2 加上生成註釋的代碼
安裝之後會在App_Start文件夾中多了SwaggerConfig.cs類，該類中的Register()方法會在應用程式啟動的時候調用
裡面好多註釋，綠綠的，還是選擇原諒他，刪掉吧，刪掉後就這剩下這些

 1 public static void Register()
 2 {
 3 　　var thisAssembly = typeof(SwaggerConfig).Assembly;
 4 
 5 　　GlobalConfiguration.Configuration
 6 　　.EnableSwagger(c =>
 7 　　{
 8 　　　　c.SingleApiVersion("v1", "WebApplication1");
 9 　　})
10 　　.EnableSwaggerUi(c =>
11 　　{
12 
13 　　});
14 }

稍微改造一下，附加個註釋xml上去

 1 public static void Register()
 2 {
 3     var thisAssembly = typeof(SwaggerConfig).Assembly;
 4 
 5     GlobalConfiguration.Configuration
 6     .EnableSwagger(c =>
 7     {
 8         c.SingleApiVersion("v1", "WebApplication1");
 9         c.IncludeXmlComments(GetXmlCommentsPath());
10     })
11     .EnableSwaggerUi(c =>
12     {    
13 
14     });
15 }
16 private static string GetXmlCommentsPath()
17 {
18     return System.String.Format(@"{0}\bin\WebApplication1.XML", System.AppDomain.CurrentDomain.BaseDirectory);
19 }

Step.3 步驟2所必須的
啟用生成xml文檔，右擊項目文件屬性 bulid發佈——Output輸出（勾選XML文件）

其實swagger他就是依賴於build時生成的這個xml來自動生成註釋上頁面的

Step.4 完成啦，看看頁面

當然，我的追求不止這些，我們來優化優化
首先，我比較喜歡將config都弄進WebApiConfig中就好，看起來比較清晰

 1 public static class WebApiConfig
 2 {
 3     public static void Register(HttpConfiguration config)
 4     {
 5         // Web API configuration and services
 6 
 7         // Web API routes
 8         config.MapHttpAttributeRoutes();
 9 
10         config.Routes.MapHttpRoute(
11             name: "DefaultApi",
12             routeTemplate: "api/{controller}/{id}",
13             defaults: new { id = RouteParameter.Optional }
14         );
15 
16         config.RegistSwagger();//添加這個swagger的Regist
17     }
18     private static void RegistSwagger(this HttpConfiguration config)
19     {
20         config.EnableSwagger("docs/{apiVersion}/swagger", c =>
21         {
22             c.SingleApiVersion("v1", "WebApplication1");
23             c.IncludeXmlComments(GetXmlCommentsPath());
24         })
25         .EnableSwaggerUi(c=> 
26         {
27 
28         });
29     }
30     private static string GetXmlCommentsPath()
31     {
32         return $@"{AppDomain.CurrentDomain.RelativeSearchPath}\WebApplication1.XML";
33     }
34 }

這個swagger的路徑也配一下吧，可以自定義一下

 1 private static void RegistSwagger(this HttpConfiguration config)
 2 {
 3     config.EnableSwagger("docs/{apiVersion}/swagger", c =>
 4     {
 5         c.SingleApiVersion("v1", "WebApplication1");
 6         c.IncludeXmlComments(GetXmlCommentsPath());
 7     })
 8     .EnableSwaggerUi("apis/{*assetPath}");//原本進入的地址是/swagger/ui/index 這樣就能換地址成/apis/index 
 9 }

這樣，我們這基本的配置就可以了，實現預期的效果——自動生成介面文檔
這裡面的配置應該還很多，等我有空更新哈，先這樣