Swashbuckle Swagger UI不显示.NET Core API自定义错误响应体问题

问题原因 #

这个差异本质是Postman作为桌面客户端不受浏览器同源策略限制，而Swagger UI是运行在浏览器中的JS应用，响应内容读取受CORS规则、响应格式配置、中间件顺序的多重限制，只要某一步配置不对就会出现响应体丢失的情况。

修复步骤 #

1. 调整中间件顺序
   中间件执行顺序直接决定了响应能不能正确返回，必须严格按照以下顺序配置：

   var app = builder.Build();
   
   // 1. 最先配置CORS，必须放在认证授权之前
   app.UseCors();
   
   // 2. 认证、授权中间件
   app.UseAuthentication();
   app.UseAuthorization();
   
   // 3. Swagger相关中间件
   app.UseSwagger();
   app.UseSwaggerUI();
   
   app.MapControllers();
   app.Run();
   

2. 完善CORS策略配置
   配置CORS时需要暴露所有响应头，允许Swagger UI所在的源读取完整响应内容：

   builder.Services.AddCors(opt =>
   {
       opt.AddPolicy("Swagger访问策略", policy =>
       {
           policy.WithOrigins("https://localhost:你的Swagger端口", "部署后Swagger访问地址")
               .AllowAnyHeader()
               .AllowAnyMethod()
               .AllowCredentials()
               // 关键配置：暴露所有响应头，允许前端JS读取
               .ExposeAllHeaders();
       });
   });
   

3. 给错误状态码配置响应类型映射
   要么给单个接口加响应类型注解，要么全局配置过滤器，让Swagger识别对应状态码的响应格式：

   // 方式1：单个接口加注解
   [HttpGet]
   [ProducesResponseType(typeof(你的自定义错误类), StatusCodes.Status401Unauthorized)]
   [ProducesResponseType(typeof(你的自定义错误类), StatusCodes.Status403Forbidden)]
   public ActionResult GetData()
   {
       // 接口逻辑
   }
   
   // 方式2：全局配置过滤器，无需逐个接口加注解
   builder.Services.AddSwaggerGen(c =>
   {
       // 你的其他Swagger配置
       c.OperationFilter<ErrorResponseTypeFilter>();
   });
   
   // 自定义过滤器实现
   public class ErrorResponseTypeFilter : IOperationFilter
   {
       public void Apply(OpenApiOperation operation, OperationFilterContext context)
       {
           operation.Responses.TryAdd("401", new OpenApiResponse { Description = "未授权" });
           operation.Responses.TryAdd("403", new OpenApiResponse { Description = "无访问权限" });
           operation.Responses.TryAdd("404", new OpenApiResponse { Description = "资源不存在" });
       }
   }
   

4. 错误响应必须指定Content-Type
   不管是自定义认证失败响应，还是全局异常中间件返回的错误，都要显式指定Content-Type为application/json，否则Swagger UI无法识别内容格式，不会渲染响应体：

   // 示例：JWT认证失败自定义响应配置
   builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
       .AddJwtBearer(opt =>
       {
           opt.Events = new JwtBearerEvents
           {
               OnChallenge = async context =>
               {
                   context.HandleResponse();
                   context.Response.StatusCode = StatusCodes.Status401Unauthorized;
                   // 必须加这一行指定内容类型
                   context.Response.ContentType = "application/json;charset=utf-8";
                   await context.Response.WriteAsync(JsonSerializer.Serialize(new
                   {
                       code = 401,
                       message = "请先登录后访问"
                   }));
               }
           };
       });
   

按照以上步骤配置后，Swagger UI就能正常展示401、403、404的自定义响应体了。

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