How to show responses example in swagger documenation

Question

I developed asp.net web API and I used swagger to API documentation and consume purposes. I need to show swagger response model sample in swagger documentation as follows

This image I got from the internet

How can I add a response example as above image

My controller as follows

/// <param name="sDate">Start date</param>
/// <param name="eDate">End date</param>
/// <param name="lCode">Location code</param>
/// <param name="page">Page number</param>
/// <param name="pageSize">Page size</param>
[Route("lobbydetail")]
[SwaggerResponse(HttpStatusCode.OK, Type = typeof(ResultOutput<List<LDetailRecord>>))]
[SwaggerResponse(HttpStatusCode.BadRequest, Type = typeof(APIError))]
[SwaggerResponse(HttpStatusCode.InternalServerError, Type = typeof(APIError))]       
public IHttpActionResult GetDetails(DateTime sDate, DateTime eDate, string lCode = null, int page = 1, int pageSize = 100)
{
    try
    {
        if (sDate > eDate)
        {
            return Content(HttpStatusCode.BadRequest, new APIError("400", "Start date is greater than end date."));
        }

        var tID = Convert.ToInt32(jwtData.GetTokenClaim(TENANT_ID));
        return Ok(dataView.GetDetailViewData(tID, sDate, eDate, lCode, page, pageSize));
    }
    catch (ArgumentException ae)
    {
        return Content(HttpStatusCode.BadRequest, new APIError("404", "Invalid location code"));
    }
    catch (Exception ex)
    {
        Logger.LogErrorEvent(ex);
        return Content(HttpStatusCode.InternalServerError, new APIError("500", "Error occurred"));
    }

}

My as follows LDetailRecord

public class LDetailRecord
{
    public DateTime TDateTime { get; set; }
    public dynamic Account { get; set; }
    public string LCode { get; set; }
    public string LName { get; set; }
    public string ConfNumber { get; set; }
    public decimal WTime { get; set; }
    public decimal AssTime { get; set; }
    public List<string> RequestedServices { get; set; }
    public string PersonRequested { get; set; }
    public string AssistedBy { get; set; }
    public string CustomerType { get; set; }
    public string CheckedInBy { get; set; }
    public string Comments { get;  set; }
    public string PreferredLanguage { get;  set; }
}

In my swagger shows as follows

I'm new to the web api and swagger, please help me, what I did wrong here

Answer 1

The answer by @Mikah-Barnett is not entirely correct when it comes to error responses.

Also, because you're returning a different type when there's an error, use the [ProducesErrorResponseType(typeof(APIError))] as well. That will let Swagger know you want a different model when there's a client error.

ProducesErrorResponseTypeAttribute(Type) - Is used for API documentation, but can only define a single error type for all errors which are specified with ProducesResponseTypeAttribute(Int32) attribute.

ProducesResponseTypeAttribute(Type, Int32) - Is used for API documentation when you want to have more detailed granularity over all the different types returned, depending on the response status code

As an example, below is what you could define per endpoint. Even better, common response type attributes can be specified at the controller level, meaning you don't need to duplicate for every endpoint.

[HttpPost]
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status500InternalServerError)]
[ProducesResponseType(typeof(NewOrderResponse), StatusCodes.Status201Created)]
public async Task<IActionResult> Post([FromBody, Required] NewOrderRequest orderRequest)

Answer 2

You need to explicitly state the return type in your methods. So, instead of

public IHttpActionResult GetDetails(...

use

public IHttpActionResult<LDetailRecord> GetDetails(...

That lets OpenAPI know exactly what you're planning to return and it will then show an example of the model in the UI.

Also, because you're returning a different type when there's an error, use the

[ProducesErrorResponseType(typeof(APIError))]

as well. That will let Swagger know you want a different model when there's a client error.

Here's a good article from MSFT documenting how this works, and below is a more complete example (from that article) showing all the pieces together.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(201)]
[ProducesResponseType(400)]
[ProducesErrorResponseType(typeof(APIError))]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}