給WebAPI的REST接口添加測試頁面（二）

在上篇文章中，我對Swagger-UI的基本功能進行了一些介紹，今天在這裏介紹一下如何在WebAPI中集成Swagger-UI。這裏以一個簡單的CRUD的REST服務爲例。 

 1     /// <summary>
 2     /// 用戶管理
 3     /// </summary>
 4     public class UserController : ApiController
 5     {
 6         static List<User> _users = new List<Controllers.User>();
 7 
 8         static int _idSeed = 0;
 9 
10 
11         /// <summary>
12         /// 添加用戶
13         /// </summary>
14         /// <param name="user">用戶數據</param>
15         /// <returns></returns>
16         public User Post(User user)
17         {
18             user.Id = ++_idSeed;
19             _users.Add(user);
20 
21             return user;
22         }
23 
24         /// <summary>
25         /// 修改用戶
26         /// </summary>
27         /// <param name="id">用戶編號</param>
28         /// <param name="user">新用戶信息</param>
29         /// <returns></returns>
30         public IHttpActionResult Put(int id, User user)
31         {
32             var current = Get(id);
33             if (current == null)
34                 return NotFound();
35 
36             user.Id = current.Id;
37             _users.Remove(current);
38             _users.Add(user);
39 
40             return Ok();
41         }
42 
43         /// <summary>
44         /// 刪除用戶
45         /// </summary>
46         /// <param name="id">用戶編號</param>
47         public void Delete(int id)
48         {
49             var current = Get(id);
50             _users.Remove(current);
51         }
52 
53         /// <summary>
54         /// 獲取用戶列表
55         /// </summary>
56         /// <returns>FFF</returns>
57         public IEnumerable<User> GetAll()
58         {
59             return _users;
60         }
61 
62         /// <summary>
63         /// 獲取指定用戶
64         /// </summary>
65         /// <param name="id">編號</param>
66         /// <returns></returns>
67         public User Get(int id)
68         {
69             return _users.Find(i => i.Id == id);
70         }
71     }
72 
73 
74     /// <summary>
75     /// 用戶
76     /// </summary>
77     public class User
78     {
79         /// <summary>
80         /// 編號
81         /// </summary>
82         public int Id { get; set; }
83 
84         /// <summary>
85         /// 名稱
86         /// </summary>
87         public string Name { get; set; }
88         
89         /// <summary>
90         /// 地址
91         /// </summary>
92         public string Address { get; set; }
93     }

View Code

 

使用Swashbuckle集成Swagger-UI

Swagger-UI自己只提供在線測試功能，要集成它還須要告訴它本項目提供的各類服務和參數信息。這裏就須要一些工做量了，不過好在許多第三方庫已經給咱們完成了這一工做。我這裏用的是Swashbuckle，使用它也比較簡單，直接使用Nuget添加其程序包便可：

    PM> Install-Package Swashbuckle

增長該程序包時，它自己會把本身相應的一些註冊的代碼添加到項目中，雖然咱們能夠不太關心這些操做，但有的時候仍是須要修改一些相關的配置的。

　　

從新編譯並運行項目，咱們就能夠在項目地址後面加一個 "/swagger"來訪問swagger測試頁面了。

　　

此時就能夠進行API的測試操做了。不過，這裏介紹的方法僅僅適用於IIS承載的WebAPI項目，對於Self Host或Owin承載的方式還有一些額外工做要作，具體請參看Swashbuckle的主頁說明文檔

 

修改標題

默認的標題是項目名稱（我這裏的"WebApplication1"），咱們經常須要把它改爲一個更加友好的名稱，修改的這個操做在前面的SwaggerConfig.cs文件中進行，找到以下代碼：

前面一個參數是Swagger-UI的版本，好像目前支持v1和v2兩種，後面就是標題了，直接修改便可。

 

集成XML註釋

前面的測試頁面雖然能夠正常工做，可是接口說明和參數說明都是空着的，顯得不夠友好，但這些實際是能夠從代碼的XML註釋中讀取出來的。要實現這一效果，須要進行以下兩步：

首先，開放註釋的XML文檔的輸出：

　　

而後，在SwaggerConfig.cs的EnableSwagger回調函數函數中，使用IncludeXmlComments函數指定XML文檔的路徑。

這樣，咱們的測試頁面就能顯示各類註釋了（貌似不支持Controller的說明）。

　　

更多高級的操做這裏就不介紹了，有須要的朋友能夠參考一下Swashbuckle的主頁說明文檔：https://github.com/domaindrivendev/Swashbuckle