给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