我想了解 ProducesResponseType 的用途。
Microsoft 将过滤器定义为指定操作返回的值和状态代码的类型。
所以我很好奇如果
- 一个人没有放置 ProductResponseType?
- 系统如何处于劣势,或者是否有负面后果?
- Microsoft API 不是已经自动地固有地知道返回的状态代码的类型/值吗?
[ProducesResponseType(typeof(DepartmentDto), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
来自 Microsoft 的文档:ProducesResponseTypeAttribute Class
最佳答案
虽然已经提交了正确答案,但我还是想举个例子。假设您已将 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()
关于c# - 网络核心 API : Purpose of ProducesResponseType,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/57678813/