.NET Core API调试模式下Swagger返回404 Undocumented错误如何解决

根因说明 #

• 调试模式下.NET Core默认启用UseDeveloperExceptionPage中间件，该中间件默认会拦截所有未处理异常并返回默认的报错页面结构，而你自定义的异常中间件如果注册顺序靠后，将无法捕获404类异常，最终返回的响应结构与Swagger中声明的错误结构不匹配
• 若你未在Swagger配置中显式声明404状态码对应的响应结构，Swagger检测到未声明的响应格式时就会返回Undocumented Error提示
• 发布到IIS时默认关闭了开发者异常页，自定义异常中间件可以正常拦截所有状态码的异常，因此响应符合预期

修复步骤 #

1. 调整中间件注册顺序 #

自定义异常中间件必须注册在所有中间件的最前方，确保可以优先拦截所有异常，示例配置如下：

var app = builder.Build();

// 第一步注册自定义异常中间件
app.UseMiddleware<你自定义的异常中间件类名>();

if (app.Environment.IsDevelopment())
{
    // 方案1：直接移除开发者异常页，所有异常都走自定义封装逻辑
    // app.UseDeveloperExceptionPage();
    
    // 方案2：保留开发者异常页仅用于排查5xx服务端错误，4xx异常交给自定义中间件处理
    app.UseDeveloperExceptionPage(new DeveloperExceptionPageOptions
    {
        StatusCodePageOptions = new StatusCodePagesOptions
        {
            HandleAsync = context => 
            {
                if (context.HttpContext.Response.StatusCode >= 500)
                {
                    return StatusCodePagesDefaults.HandleAsync(context);
                }
                return Task.CompletedTask;
            }
        }
    });
}

// 后续注册Swagger、路由、鉴权、端点映射等其他中间件
app.UseSwagger();
app.UseSwaggerUI();
// ...其余中间件

2. Swagger显式声明404响应 #

任选以下一种方式配置即可：

• 全局配置：在Swagger注入时添加全局通用响应声明

builder.Services.AddSwaggerGen(opt =>
{
    opt.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    // 全局声明所有接口都可能返回404状态码，参数为你自定义的错误返回模型类
    opt.AddUniversalResponseType(StatusCodes.Status404NotFound, typeof(你的错误返回模型类));
});

• 单接口配置：在对应接口方法上添加响应类型特性

[HttpGet("{id}")]
[ProducesResponseType(typeof(你的错误返回模型类), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(接口正常返回模型类), StatusCodes.Status200OK)]
public async Task<IActionResult> 查询数据(int id)
{
    // 业务逻辑
}

3. 验证效果 #

启动调试后，直接调用会返回404的接口，确认返回的响应结构与你声明的错误结构一致，此时Swagger即可正常识别并展示状态码和错误信息。

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