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）返回代码可以派上用场。假设如果其中一个失败状态代码返回描述问题的模型，您可以指定该情况下的状态代码生成与成功情况不同的内容。

Answer 3

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

Answer 4

3种不同的使用选择在所有应用程序控制器中：public void Configure(IApplicationBuilder app, IWebHostEnvironment env){        app.UseSwaggerResponseCheck();  //...}使用 ValidateStatusCodes 属性的每个控制器操作：[ApiController][Route("[controller]")]public class ExampleController : ControllerBase{    [HttpGet]    [ValidateStatusCodes] // <-- Use this    [SwaggerOperation("LoginUser")]    [SwaggerResponse(statusCode: StatusCodes.Status200OK, type: null, description: "signed user email account")]    [SwaggerResponse(statusCode: StatusCodes.Status400BadRequest, type: null, description: "wrong email or password")]    [Route("/users/login")]    public virtual IActionResult LoginUser([FromQuery][Required()] string email, [FromQuery] string password)    {            if (email == "[e-mail]")              return Ok("success");            else if (email == "")              return BadRequest("email required");            else              return NotFound("user not found"); // 500 - InternalServerError because not attributed with SwaggerResponse.    }    // ...    [HttpGet]    [ValidateStatusCodes] // <-- Use this    [ProducesResponseType(type: typeof(Account), StatusCodes.Status200OK)]    [ProducesResponseType(StatusCodes.Status400BadRequest)]    [Route("/users/login2")]    public virtual IActionResult LoginUser2([FromQuery][Required()] string email, [FromQuery] string password)    {            if (email == "[e-mail]")              return Ok("success").Validate();            else if (email == "")              return BadRequest("email required").Validate();            else              return NotFound("user not found").Validate(); // Throws error in DEBUG or Development.    }}使用 IStatusCodeActionResult.Validate() 的每个结果：[ApiController][Route("[controller]")]public class ExampleController : ControllerBase{    [HttpGet]    [SwaggerOperation("LoginUser")]    [SwaggerResponse(statusCode: StatusCodes.Status200OK, type: null, description: "signed user email account")]    [SwaggerResponse(statusCode: StatusCodes.Status400BadRequest, type: null, description: "wrong email or password")]    [Route("/users/login")]    public virtual IActionResult LoginUser([FromQuery][Required()] string email, [FromQuery] string password)    {            if (email == "[e-mail]")              return Ok("success").Validate();            else if (email == "")              return BadRequest("email required").Validate();            else if (email == "secret")              return Unauthorized("hello");                 // Passed, independent of SwaggerResponse attribute.            else              return NotFound("user not found").Validate();                 // 500 - InternalServerError because not attributed with SwaggerResponse.    }    // ...    [HttpGet]    [ProducesResponseType(type: typeof(Account), StatusCodes.Status200OK)]    [ProducesResponseType(StatusCodes.Status400BadRequest)]    [Route("/users/login2")]    public virtual IActionResult LoginUser2([FromQuery][Required()] string email, [FromQuery] string password)    {            if (email == "[e-mail]")              return Ok("success").Validate();            else if (email == "")              return BadRequest("email required").Validate();            else              return NotFound("user not found").Validate(); // Throws error in DEBUG or Development.    }}