Swashbuckle.AspNetCore实现Swagger文档400状态码多错误描述配置

核心现状澄清 #

很多升级到新版的开发者都会遇到这个认知偏差：旧版本内置的SwaggerResponse特性不是被彻底废弃了，而是因为核心包做体积精简，把注解类功能拆分到了独立的扩展包里，不是功能被砍。
而原生提供的ProducesResponseType特性从设计之初就只负责声明接口返回的状态码和对应数据模型类型，不承载自定义描述文案的配置能力，自然没法直接实现多行错误提示的文档展示效果。

可落地的实现方案 #

方案1：使用官方注解扩展包（最贴近旧版使用习惯） #

这是改动最小、最容易上手的方案，完全不用写自定义逻辑：

• 第一步安装官方配套的扩展包Swashbuckle.AspNetCore.Annotations
• 第二步在Swagger服务配置中开启注解支持：

builder.Services.AddSwaggerGen(c =>
{
    c.EnableAnnotations();
});

• 第三步直接在需要配置的接口/控制器上标注特性，把多行错误提示作为描述参数传入，直接用真实换行分隔每条错误即可：

[HttpPost]
[SwaggerResponse(StatusCodes.Status400BadRequest, 
    Description = @"Invalid format
Field is required
Should be greater than 10")]
public IActionResult SubmitForm(FormModel model)
{
    // 接口业务逻辑
}

这种配置渲染出的Swagger文档，会自动在400状态码对应的Description列下逐行展示所有错误提示，完全匹配预期的排版结构。

方案2：自定义操作过滤器（适合全局统一配置场景） #

如果需要给所有接口统一配置400状态码的通用错误提示，不需要每个接口单独加特性，可以通过操作过滤器批量处理：

• 实现自定义的IOperationFilter，逻辑非常简单：遍历当前接口的响应配置，找到状态码为400的响应项，直接替换它的描述为预设的多行错误文本：

public class BadRequestDescriptionFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 预设需要展示的多行错误内容
        const string badRequestDoc = @"Invalid format
Field is required
Should be greater than 10";
        
        var badRequestCode = StatusCodes.Status400BadRequest.ToString();
        if (operation.Responses.ContainsKey(badRequestCode))
        {
            operation.Responses[badRequestCode].Description = badRequestDoc;
        }
    }
}

• 在Swagger服务配置中注册这个过滤器，即可实现全局所有接口的400响应描述自动替换：

builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<BadRequestDescriptionFilter>();
});

常见配置避坑 #

• 写多行描述的时候不要手动用空格凑缩进，Swagger UI渲染响应表格的时候会自动保持列对齐，只要用真实换行分隔每条错误提示就能匹配预期排版
• 不要把转义的\n作为普通字符串硬拼进描述里（比如写成"Invalid format\\nField is required"），那样会直接把反斜杠渲染成普通文本，不会触发换行效果
• 如果需要针对不同接口配置差异化的400错误提示，可以在自定义过滤器里读取接口标注的自定义元数据，动态拼接对应场景的错误列表，不需要为每个接口重复写配置

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