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

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

    /// <summary>
    /// 用戶管理
    /// </summary>
    public class UserController : ApiController
    {
        static List<User> _users = new List<Controllers.User>();

        static int _idSeed = 0;


        /// <summary>
        /// 添加用戶
        /// </summary>
        /// <param name="user">用戶數據</param>
        /// <returns></returns>
        public User Post(User user)
        {
            user.Id = ++_idSeed;
            _users.Add(user);

            return user;
        }

        /// <summary>
        /// 修改用戶
        /// </summary>
        /// <param name="id">用戶編號</param>
        /// <param name="user">新用戶信息</param>
        /// <returns></returns>
        public IHttpActionResult Put(int id, User user)
        {
            var current = Get(id);
            if (current == null)
                return NotFound();

            user.Id = current.Id;
            _users.Remove(current);
            _users.Add(user);

            return Ok();
        }

        /// <summary>
        /// 刪除用戶
        /// </summary>
        /// <param name="id">用戶編號</param>
        public void Delete(int id)
        {
            var current = Get(id);
            _users.Remove(current);
        }

        /// <summary>
        /// 獲取用戶列表
        /// </summary>
        /// <returns>FFF</returns>
        public IEnumerable<User> GetAll()
        {
            return _users;
        }

        /// <summary>
        /// 獲取指定用戶
        /// </summary>
        /// <param name="id">編號</param>
        /// <returns></returns>
        public User Get(int id)
        {
            return _users.Find(i => i.Id == id);
        }
    }


    /// <summary>
    /// 用戶
    /// </summary>
    public class User
    {
        /// <summary>
        /// 編號
        /// </summary>
        public int Id { get; set; }

        /// <summary>
        /// 名稱
        /// </summary>
        public string Name { get; set; }
        
        /// <summary>
        /// 地址
        /// </summary>
        public string Address { get; set; }
    }

 

使用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