Net Core API：ProducesResponseType 的目的

Question

我想了解的目的 ProducesResponseType.

微软定义为 a filter that specifies the type of the value and status code returned by the action.

所以我很好奇如果

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

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

来自 Microsoft 的文档：ProducesResponseTypeAttribute 类

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";  

});

有一个像这样的测试控制器操作端点：

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

将产生如下所示的 swagger 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 分析器添加到您的项目中，以接收一些有用的警告。

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

Answer 2

我认为它可以为非成功 (200) 返回码派上用场。假设其中一个失败状态代码返回一个描述问题的模型，您可以指定这种情况下的状态代码产生与成功案例不同的东西。您可以阅读更多相关信息并在此处找到示例：https : //docs.microsoft.com/en-us/aspnet/core/web-api/action-return-types?view=aspnetcore-2.2

Answer 3

它用于为 API 探索/可视化工具（例如 Swagger ( https://swagger.io/ )）生成开放 API 元数据，以在文档中指示控制器可能返回的内容。