Net Core API：ProducesResponseType 的作用是什么？

Question

Net Core API：ProducesResponseType 的作用是什么？

c#.netasp.net-core.net-core

93

我想了解ProducesResponseType的目的。

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

因此，我很好奇如果：

一个人不设置ProductResponseType会有什么后果？
系统会受到不利影响吗？还是存在负面后果？
Microsoft API不已经自动固有地了解返回的状态代码的类型/值吗？

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

来自Microsoft的文档：ProducesResponseTypeAttribute类

- user11973685

31

据我所知，它仅仅是一份文档。如果您使用像NSwag或Swashbuckle这样的工具，根据该属性，它将显示端点的可能响应。我不知道它在除生成API文档之外有任何其他影响。 - Chris Pratt

@ChrisPratt 可以随意发布答案，我会发送积分，谢谢！ - user11973685

1

我不确定这是唯一的答案。其他人可能知道我不知道的东西。我从来没有在任何不涉及API文档的讨论中看到过这个属性。这并不意味着它实际上没有其他用途。 - Chris Pratt

请查看我的答案，一些反射技巧可以用于不仅仅是文档，还可以用于运行时检查（例如测试）。 - Vladimir Koltunov

4个回答

16

我认为它对非成功（200）的返回代码很有用。比如说，如果一个失败状态码返回了描述问题的模型，你可以指定在这种情况下该状态码会产生与成功情况不同的输出。你可以在这里阅读更多相关内容并查找示例：https://learn.microsoft.com/en-us/aspnet/core/web-api/action-return-types?view=aspnetcore-2.2

- Mohammad

14

这段引用的意思是，“这个属性可以产生更加详细的响应信息，用于生成类似Swagger这样工具生成的Web API帮助页面。”因此，我猜测它主要用于文档编写，并可能可被静态代码分析使用。 - Andy

4

看起来是更多的无用信息。如果样板式的 XML 注释还不足以使您的代码混乱不堪，现在又有了这个。不过，在文本编辑器中看起来真的很聪明！ - user1172763

11

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

- Sean

0

SwaggerResponse和ProducesResponseType属性的检查

你可以在dotnet (.NET 6为例)中使用this extension，强制开发者将OpenAPI（Swagger）描述与方法实现同步。

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 == "email@gmail.com")
              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 == "email@gmail.com")
              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 == "email@gmail.com")
              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 == "email@gmail.com")
              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.
    }
}

- Vladimir Koltunov

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，

- Siavash Mortazavi · Accepted Answer

虽然正确答案已经提交，但我愿意提供一个例子。假设您已经将 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 分析器添加到项目中，以接收一些有用的警告。

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