如何在招摇文档中显示响应示例

Question

我开发了 asp.net Web API，我使用 swagger 来编写 API 文档和使用目的。我需要在 swagger 文档中显示 swagger 响应模型示例，如下所示

这张图是网上找的

如何添加如上图的响应示例

我的控制器如下

/// <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"));
    }

}

我的如下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; }
}

在我的招摇表演中如下

我是web api和swagger的新手，请帮助我，我在这里做错了什么

Answer 1

@Mikah-Barnett 的回答在错误响应方面并不完全正确。

此外，由于您在出错时返回的是不同的类型，因此请使用 [产生ErrorResponseType(typeof(APIError))] 以及。当出现客户端错误时，这会让 Swagger 知道您需要不同的模型。

ProducesErrorResponseTypeAttribute(Type) - 用于 API 文档，但只能为使用 ProducesResponseTypeAttribute(Int32) 属性指定的所有错误定义单一错误类型。

ProducesResponseTypeAttribute(Type, Int32) - 当您希望根据响应状态代码对返回的所有不同类型有更详细的粒度时，用于 API 文档

例如，以下是您可以为每个端点定义的内容。更好的是，可以在控制器级别指定通用响应类型属性，这意味着您不需要为每个端点复制。

[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

您需要在方法中明确声明返回类型。所以，而不是

public IHttpActionResult GetDetails(...

使用

public IHttpActionResult<LDetailRecord> GetDetails(...

这让 OpenAPI 确切知道您打算返回什么，然后它将在 UI 中显示模型的示例。

另外，因为您在出现错误时返回的是不同的类型，所以请使用

[ProducesErrorResponseType(typeof(APIError))]

也是。当出现客户端错误时，这会让 Swagger 知道您需要不同的模型。

这里有一个 good article from MSFT 记录了它是如何工作的，下面是一个更完整的示例（来自那篇文章），展示了所有部分。

/// <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);
}