c# - 为多个 HttpStatusCodes 设置一个 ProducesResponseType typeof

Question

我正在设置 ProducesResponseType，以便用 Swagger 记录它。

如果响应成功(OK => 200)，那么它会生成一个 IEnumerable。

[ProducesResponseType(typeof(IEnumerable<MyModel>), 200)]

但是当我遇到异常时，我会捕获它，然后生成我的自定义 APIError 类的对象。当我填充对象时，我可以设置不同的 HttpStatusCodes，但最后，我想要的是能够将 ProducesResponseType 设置为我的 APIError 类，用于所有剩余的 HttpStatusCodes。我的意思是，我可以获得 BadRequest、ServerInternalError、Forbidden 等，但它们都将具有相同的响应类型 (ApiError)。有没有办法为所有错误的http代码设置这行代码？还是需要一个一个设置？

[ProducesResponseType(typeof(ApiError), ???)]

最终结果应该是这样的:

[ProducesResponseType(typeof(IEnumerable<MyModel>), 200)]
[ProducesResponseType(typeof(ApiError), AllFailureHttpCodes)]

Answer 1

我担心这是不可能的，至少不是每个 Action 。

IApiResponseMetadataProvider(参见 here)只有一个 int StatusCode { get; 属性已定义，它用于 ProducesAttribute 和 ProducesResponseTypeAttribute。

但是，在您的特殊情况下，您可以将其注册为全局过滤器，因为无论是 GET、POST、PUT 还是 DELETE，所有操作的错误结果都应该相同。

services.AddMvc(options =>
{
    options.Filters.Add(new Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute(typeof(ApiError), 400));
    options.Filters.Add(new Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute(typeof(ApiError), 401));
    options.Filters.Add(new Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute(typeof(ApiError), 409));
});

然后这些应该应用于您的 MVC/WebAPI 应用程序中的每个操作。

警告语

但是，我个人认为这种用法是错误的，因为它表明您的每个方法都可以处理这些类型的错误。例如 409 是专门针对冲突的，在您使用它的 WebAPI 中，当更新资源时出现错误，即当使用乐观并发时，记录被另一个用户更改，因此记录的版本被更改并且更新失败.

将这些添加到每个方法都是错误的。如果您的操作确实处理了此状态代码，则您应该只添加状态代码。例如，409 仅适用于 PUT 和 POST 方法。其中 404 可能适合 GET 和 PUT(更新)，但不太适合 POST(插入)。

这尤其糟糕，当你使用诸如 Swagger 之类的工具生成 Api Docs 时，你只会得到一个错误的文档。您应该将 ProducesResponseType 视为一种文档形式，因此不应使用过于通用的方法。

更新:ASP.NET Core 2.2

在 ASP.NET Core 2.2 中，Swagger API 支持得到了极大改进，这还包括 convention based响应类型和代码。

它已经带有一组很好的默认约定，但您也可以覆盖它并提供您自己的约定方法。