.NET Core API使用自定义异常中间件时如何在Swagger生成错误响应

方案1：单接口标注响应类型（灵活控制单个接口的响应说明） #

直接在控制器接口方法上添加[ProducesResponseType]特性，指定对应状态码的返回模型即可，示例如下：
首先定义全局统一返回的错误模型（需和ErrorHandlingMiddleware捕获异常后返回的结构完全一致）：

public class ApiErrorResponse
{
    // 自定义错误枚举
    public ErrorCode Code { get; set; }
    // 错误提示信息
    public string Message { get; set; }
}

然后给对应接口添加特性标注：

[HttpPost("login")]
[ProducesResponseType(StatusCodes.Status200OK)]
// 400状态码绑定自定义错误模型
[ProducesResponseType(typeof(ApiErrorResponse), StatusCodes.Status400BadRequest)]
// 按需添加其他可能的错误状态码，比如401、500
[ProducesResponseType(typeof(ApiErrorResponse), StatusCodes.Status500InternalServerError)]
public async Task<IActionResult> Test(LoginRequest req)
{
    if (user.Banned)
    {
        throw new BadRequestHorseedoException(ErrorCode.BANNED, "User is banned");
    }

    return Ok();
}

配置完成后Swagger会自动生成对应状态码的响应说明。

方案2：全局统一添加（适合所有接口共用同一套错误响应规则的场景） #

如果不需要单独控制每个接口的响应说明，可以自定义Swagger操作过滤器批量注入错误响应：

1. 编写自定义操作过滤器

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class GlobalErrorResponseFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 定义需要全局添加的错误状态码和说明
        var errorStatusCodes = new Dictionary<int, string>
        {
            { 400, "请求参数错误/业务逻辑校验失败" },
            { 401, "未授权访问" },
            { 403, "权限不足" },
            { 500, "服务器内部错误" }
        };

        foreach (var (statusCode, description) in errorStatusCodes)
        {
            // 已存在的响应跳过，避免重复
            if (operation.Responses.ContainsKey(statusCode.ToString()))
                continue;

            // 关联自定义错误模型的Schema
            var errorSchema = context.SchemaGenerator.GenerateSchema(typeof(ApiErrorResponse), context.SchemaRepository);
            operation.Responses.Add(statusCode.ToString(), new OpenApiResponse
            {
                Description = description,
                Content = new Dictionary<string, OpenApiMediaType>
                {
                    ["application/json"] = new OpenApiMediaType
                    {
                        Schema = errorSchema
                    }
                }
            });
        }
    }
}

2. 在Program.cs（或Startup.cs）的Swagger配置中注册过滤器

builder.Services.AddSwaggerGen(c =>
{
    // 原有Swagger配置保留
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    // 注册全局错误响应过滤器
    c.OperationFilter<GlobalErrorResponseFilter>();
});

配置完成后所有接口的Swagger文档都会自动生成对应状态码的自定义错误响应说明，无需单独给接口加特性。

内容的提问来源于stack exchange，提问作者Merynek