IT輪子系列（三）——如何給返回類型添加注釋——Swagger的使用（二）

前言

一般對外提供API，都會統一一個返回類型，比如所有的接口都統一返回HttpResponseMessage。這樣當我們在方法上添加///注釋時，是無法清楚的知道都返回字段都又那些以及它們的數據類型是什么。如下圖所生成的文檔所示：

、

從圖中，我們看到文檔只有輸入參數的說明，而對於返回的類型是什么，有那些字段都是不清楚的。這對於調用第三方調用是很不友好的。

在實際項目中，偶然發現，Swashbuckle 提供一個返回類型屬性，很好的解決了這個問題。

如代碼所示：

/// </summary>
    public class UserController : BaseController
    {
        /// <summary>
        /// 獲取用戶信息
        /// </summary>
        /// <param name="model">獲取用戶信息模型</param>
        /// <returns></returns>
        [HttpPost]
        //添加方法修飾屬性返回類型說明
        [SwaggerResponse(HttpStatusCode.OK, Type = typeof(ResultInfo<UserInfo>))]
        public HttpResponseMessage GetUserInfo([FromBody]GetUserInfoModel model)
        {
            ResultInfo<UserInfo> result = new ResultInfo<UserInfo>();
            try
            {
                UserInfo user = new UserInfo();
                user.Name = "Peter";
                user.Phone = model.phone;
                user.Email = "[e-mail]";
                result.Data = user;
            }
            catch (Exception ex)
            {
                result.Status = "FAIL";
                result.Msg = ex.Message;
            }         
            
            return toJson(result);
        }
    }

當我們給方法添加SwaggerResponse屬性修飾的時候，在生成的文檔中就可以看到返回類型拉。