使用Swashbuckle構建RESTful風格文件

神牛003發表於2018-05-08
REST

　　本次和大家分享的是Swagger to WebApi的nuget包Swashbuckle；因為專案需要統一api文件的風格，並要支援多種開發語言（C#，java，python），所以首先想到的是swagger來構建api文件，本章講解的是對.net的webpi來生成文件，後續會將java的springmvc+swagger來構建介面文件。

  • 準備工作
  • 快速構建簡易api文件
  • swagger文件支援在header中增加Token引數

. 準備工作

　　首先創webapi專案，然後通過nuget管理器安裝Swashbuckle的包，我這裡通過console命令安裝：

　　 Install-Package Swashbuckle -Version 5.6.0 

　　注意只需要安裝這個包就行了，其他的會自動引用，由於Swashbuckle包含了swagger的引用，所以不用再單獨操作引用了。

. 快速構建簡易api文件

　　如上安裝完Swashbuckle後其實就能夠直接執行看效果了，我這裡的訪問路徑是： http://localhost:51847/swagger/ui/index ，注意：/swagger/ui/index 是預設固定的路徑，這是nuget包封裝的路徑，訪問後能看到如下介面效果：

　　

　　一個簡易的文件就弄好了，swagger的顏色看起來搭配不錯；由於大多數介面都是post請求方式，因此咋們以/api/values的post介面為例如：

　　

　　對於介面文件而言，上面文件存在如下一些疏漏：

  • 未說明方法的功能
  • 引數屬性的描述沒有
  • 返回屬性的描述沒有

　　為了方便其他人員對接介面，所以對介面文件我們需要增加一些描述，要增加描述這裡就要知曉：Swashbuckle是通過xml檔案來讀取配置資訊的，該xml檔案裡面包含了我們在程式碼中對方法，對類，對引數，對返回值做的文字描述；首先定義一個請求和響應的實體 如：

 1 /// <summary>
 2     /// 登入請求
 3     /// </summary>
 4     public class MoLoginRq
 5     {
 6         /// <summary>
 7         /// 賬號
 8         /// </summary>
 9         public string UserName { get; set; }
10         /// <summary>
11         /// 密碼
12         /// </summary>
13         public string UserPwd { get; set; }
14     }
15 
16     /// <summary>
17     /// 登入返回
18     /// </summary>
19     public class MoLoginRp
20     {
21         /// <summary>
22         /// 登入返回的token
23         /// </summary>
24         public string Token { get; set; }
25     }
View Code

　　新增一個登入介面，程式碼如：

 1 /// <summary>
 2         /// 登入介面
 3         /// </summary>
 4         /// <param name="rq">請求</param>
 5         /// <returns>響應</returns>
 6         [HttpPost]
 7         public MoLoginRp Login(MoLoginRq rq)
 8         {
 9             MoLoginRp rp = new MoLoginRp();
10 
11             rp.Token = Guid.NewGuid().ToString();
12 
13             return rp;
14         }

　　到這裡基本的動作都做完了，剩下的是上面我們說的xml檔案怎麼來，又怎麼和swagger關聯；

　　首先，看專案的App_Start資料夾裡面應該在安裝nuget包的時候會自動增加一個 SwaggerConfig.cs 檔案，裡面就是swagger使用的一些設定，我們需要找到被註釋的： //c.IncludeXmlComments(GetXmlCommentsPath()); 程式碼，取消註釋並建立一個 GetXmlCommentsPath() 方法（獲取xml註釋檔案路徑） 如：

1 public static string GetXmlCommentsPath()
2         {
3             //D:/WebApplication/bin/WebApplication.xml
4             return Path.Combine(
5                 AppDomain.CurrentDomain.BaseDirectory,
6                 "bin",
7                 string.Format("{0}.XML", typeof(SwaggerConfig).Assembly.GetName().Name));
8         }

　　這個時候程式碼基本完成了，還需要我們通過vs設定一下生成專案時自動建立xml檔案，如下：滑鼠右鍵起始專案-》屬性-》生成-》勾選xml檔案

　　

　　然後，滑鼠右鍵重新生成下專案，這個時候bin目錄就有了WebApplication.xml

　　

　　這個xml檔案內容就是一些註釋的資訊，具體各位自己點看看下xml內容；到這裡我們設定和程式碼都弄完了，來看下swagger頁面效果，通過預覽 http://localhost:51847/swagger/ui/index ：

　　

　　這個時候我們增加的一些文字說明就完成了，這個時候細心的朋友能夠看出來我們的Action方法名稱沒識別出來，這不符合我們命名規範，這裡有兩種解決方案：

  • 在action方法上增加 [ActionName("Login")] 標記
  • 修改WebApiConfig.cs檔案的路由如："api/{controller}/{action}/{id}"

　　這裡我採用後者，為了統一通過方法名來識別對應介面：

　　

swagger文件支援在header中增加Token引數

　　對於api介面，我們通常在登入後的其他操作都會讓呼叫方傳遞授權的token，而token一般做法是放在請求的header裡面，swagger文件為了測試方便可以把token放在header作為引數傳遞；首先建立測試介面GetNames：

 1         /// <summary>
 2         /// 獲取使用者名稱稱列表
 3         /// </summary>
 4         /// <returns></returns>
 5         [HttpPost]
 6         public List<string> GetNames()
 7         {
 8             List<string> list = new List<string> {"神牛001","神牛002", "神牛003" };
 9 
10             return list;
11         }

　　然後在App_Start/SwaggerConfig.cs檔案中新增：

1 c.ApiKey("apiKey")
2      .Description("授權token")
3      .Name("token")
4      .In("header");

　　並啟動：

1 EnableSwaggerUi(c =>
2      {
3           c.EnableApiKeySupport("token", "header");
4     });

　　然後啟動並在swagger介面輸入：

　　

　　這個時候點選try it out請求介面，能夠在看到請求裡面包含了token資訊：

　　

相關文章