Question

我开发了asp.net Web API，并用招摇过头的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; }
}

在我的招展中显示如下

我是网络api的新手，请帮帮我，我在这里做错了什么

Answer 1

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

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

Answer 2

对于错误响应，@Mikah-Barnett给出的答案并不完全正确。

此外，由于发生错误时您将返回其他类型，请使用 [ProducesErrorResponseType（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)

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

2 个答案: