c# - 网络核心 API : Purpose of ProducesResponseType

Question

我想了解 ProducesResponseType 的用途。

Microsoft 将过滤器定义为指定操作返回的值和状态代码的类型。

所以我很好奇如果

• 一个人没有放置 ProductResponseType？
• 系统如何处于劣势，或者是否有负面后果？
• Microsoft API 不是已经自动地固有地知道返回的状态代码的类型/值吗？

[ProducesResponseType(typeof(DepartmentDto), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]

来自 Microsoft 的文档:ProducesResponseTypeAttribute Class

Answer 1

虽然已经提交了正确答案，但我还是想举个例子。假设您已将 Swashbuckle.AspNetCore 包添加到您的项目中，并在 Startup.Configure(...) 中使用它，如下所示:

app.UseSwagger();
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "My Web Service API V1");
    options.RoutePrefix = "api/docs";  

});

有一个像这样的测试 Controller 操作端点:

[HttpGet]        
public ActionResult GetAllItems()
{
    if ((new Random()).Next() % 2 == 0)
    {
        return Ok(new string[] { "value1", "value2" });
    }
    else
    {
        return Problem(detail: "No Items Found, Don't Try Again!");
    }
}

将导致像这样的 UI 卡片/部分(运行项目并导航到/api/docs/index.html):

如您所见，没有为端点提供“元数据”。

现在，将端点更新为:

[HttpGet]
[ProducesResponseType(typeof(IEnumerable<string>), 200)]
[ProducesResponseType(404)]
public ActionResult GetAllItems()
{
    if ((new Random()).Next() % 2 == 0)
    {
        return Ok(new string[] { "value1", "value2" });
    }
    else
    {
        return Problem(detail: "No Items Found, Don't Try Again!");
    }
}

这根本不会改变端点的行为，但现在 swagger 页面看起来像这样:

这要好得多，因为现在客户端可以看到可能的响应状态代码是什么，以及对于每个响应状态，返回数据的类型/结构是什么。请注意，虽然我没有为 404 定义返回类型，但 ASP.NET Core(我使用的是 .NET 5)足够聪明，可以将返回类型设置为 ProblemDetails .

如果这是您要采用的路径，最好添加 Web API Analyzer到您的项目，接收一些有用的警告。

附注我还想在 app.UseSwaggerUI(...) 配置中使用 options.DisplayOperationId();。通过这样做，swagger UI 将显示映射到每个端点的实际 .NET 方法的名称。例如，上面的端点是对/api/sample 的 GET，但实际的 .NET 方法称为 GetAllItems()