IT轮子系列(三)——如何给返回类型添加注释——Swagger的使用(二)_.NET_编程开发_程序员俱乐部

中国优秀的程序员网站程序员频道CXYCLUB技术地图
热搜:
更多>>
 
您所在的位置: 程序员俱乐部 > 编程开发 > .NET > IT轮子系列(三)——如何给返回类型添加注释——Swagger的使用(二)

IT轮子系列(三)——如何给返回类型添加注释——Swagger的使用(二)

 2017/11/1 23:11:30  Hi-Peter  程序员俱乐部  我要评论(0)
  • 摘要:前言一般对外提供API,都会统一一个返回类型,比如所有的接口都统一返回HttpResponseMessage。这样当我们在方法上添加///注释时,是无法清楚的知道都返回字段都又那些以及它们的数据类型是什么。如下图所生成的文档所示:、从图中,我们看到文档只有输入参数的说明,而对于返回的类型是什么,有那些字段都是不清楚的。这对于调用第三方调用是很不友好的。在实际项目中,偶然发现,Swashbuckle提供一个返回类型属性,很好的解决了这个问题。如代码所示:1///</summary>
  • 标签:使用 注释

前言

一般对外提供API,都会统一一个返回类型,比如所有的接口都统一返回HttpResponseMessage。这样当我们在方法上添加///注释时,是无法清楚的知道都返回字段都又那些以及它们的数据类型是什么。如下图所生成的文档所示:

从图中,我们看到文档只有输入参数的说明,而对于返回的类型是什么,有那些字段都是不清楚的。这对于调用第三方调用是很不友好的。

在实际项目中,偶然发现,Swashbuckle 提供一个返回类型属性,很好的解决了这个问题。

如代码所示:

class="code_img_closed" src="/Upload/Images/2017110123/0015B68B3C38AA5B.gif" alt="">
 1 /// </summary>
 2     public class UserController : BaseController
 3     {
 4         /// <summary>
 5         /// 获取用户信息
 6         /// </summary>
 7         /// <param name="model">获取用户信息模型</param>
 8         /// <returns></returns>
 9         [HttpPost]
10         //添加方法修饰属性返回类型说明
11         [SwaggerResponse(HttpStatusCode.OK, Type = typeof(ResultInfo<UserInfo>))]
12         public HttpResponseMessage GetUserInfo([FromBody]GetUserInfoModel model)
13         {
14             ResultInfo<UserInfo> result = new ResultInfo<UserInfo>();
15             try
16             {
17                 UserInfo user = new UserInfo();
18                 user.Name = "Peter";
19                 user.Phone = model.phone;
20                 user.Email = "itwheels@163.com";
21                 result.Data = user;
22             }
23             catch (Exception ex)
24             {
25                 result.Status = "FAIL";
26                 result.Msg = ex.Message;
27             }         
28             
29             return toJson(result);
30         }
31     }
logs_code_collapse">View Code

当我们给方法添加SwaggerResponse属性修饰的时候,在生成的文档中就可以看到返回类型拉。

 

发表评论
用户名: 匿名