IT wheel series (iii) -- how to add comments to the return type -- Use of Swagger (II), wheel swagger

IT wheel series (iii) -- how to add comments to the return type -- Use of Swagger (II), wheel swagger

Preface

Generally, when APIs are provided externally, a uniform return type is applied. For example, all interfaces return a uniform HttpResponseMessage. In this way, when we add a // annotation to the method, we cannot clearly know what fields are returned and what their data types are. As shown in the generated document:

,

, We can see that the document only describes the input parameters, but it is unclear about the returned type and the fields. This is unfriendly to calling third-party calls.

In actual projects, it was discovered by accident that Swashbuckle provided a return type attribute, which effectively solved this problem.

As shown in the Code:

1 /// </summary> 2 public class UserController: baseController 3 {4 /// <summary> 5 // obtain user information 6 /// </summary> 7 /// <param name = "model"> obtain user information model </param> 8 // <returns> </returns> 9 [HttpPost] 10 // Add method modifier attribute return type description 11 [SwaggerResponse (HttpStatusCode. OK, Type = typeof (ResultInfo <UserInfo>)] 12 public HttpResponseMessage GetUserInfo ([FromBody] GetUserInfoModel model) 13 {14 ResultInfo <UserInfo> result = new ResultInfo <UserInfo> (); 15 try16 {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}

View Code

When we add the SwaggerResponse attribute to the method, we can see the return type pull in the generated document.