Response model for specific status codes using Swagger

Question

I use Swagger to document my REST API (using asp.net web api 2). Is there a way in swagger to give response models for every possible response for a given api call? I comment on the response of the status code using XML comments as follows:

/// <summary> /// Save a person /// </summary> /// <response code="200">Ok</response> /// <response code="400">Bad Request</response> /// <response code="500">Internal Server error</response> public HttpResponseMessage SavePerson() {...} 

Answer 1

You can try using cref = "TYPE HERE" in your XML comments like this.

 /// <response code="400" cref="CustomErrorModel">Bad Request</response> 

In ut, I would suggest using the annotations that Swagger gives you.

 [SwaggerResponse(HttpStatusCode.OK, Type = typeof(OnlineMerchantQueryResponseInformation))] 

associate your controllers with this.

Answer 2

Your signature says that you are returning an HttpResponseMessage, not a data model. If you return IActionResult and use ASP.NET Core, you can use the "ProducesResponseType" attribute:

 [ProducesResponseType(typeof(IEnumerable<YourModel>), 200)] 

ProducesResponsesType is located in the Microsoft.AspNetCore.Mvc namespace.

See https://github.com/domaindrivendev/Swashbuckle.AspNetCore#list-operation-responses "Explicit Answers"

Answer 3

If you use Swashbuckle, you can try

  [SwaggerResponse(200, typeof(CustomModel))] 

and you additionally add a comment for this type of response as an optional third parameter

 [SwaggerResponse(200, typeof(CustomModel), "returns a new id of the bla bla")] 

Note. The attribute is in the Swashbuckle.AspNetCore.Annotations namespace