Core托管Blazor WASM的Swagger JSON及UI端点返回404问题排查

我在ASP.NET Core托管的Blazor WASM项目中配置了Swagger，但访问https://localhost:5001/swagger/v1/swagger.json或/swagger/index.html时均返回404。以下是完整代码，请求排查配置遗漏点：

代码片段 #

ServiceCollectionExtension.cs #

namespace AlprDashboard.Server.Domain
{
    public static class ServiceCollectionExtension
    {
        
       // OTHER CODES...

        public static void UseSwaggerExtension(this IServiceCollection services)
        {
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "ALPR Dahsboard API", Version = "v1" });
            });
        }
    }
}

Program.cs #

using AlprDashboard.Server.Domain;
using Microsoft.AspNetCore.Hosting.StaticWebAssets;
using Serilog;

var builder = WebApplication.CreateBuilder(args);

StaticWebAssetsLoader.UseStaticWebAssets(builder.Environment, builder.Configuration);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

builder.Host
        .UseSerilog((hostingContext, loggerConfiguration) =>
        {
            loggerConfiguration.ReadFrom.Configuration(hostingContext.Configuration);
        });

builder.Services.ConfigureApplicationCors(builder.Configuration);
builder.Services.ConfigureApplicationAuthentication(builder.Configuration);
builder.Services.UseSwaggerExtension();
builder.Services.ConfiguredExtensions();


var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseWebAssemblyDebugging();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "ALPR Dahsboard API");
});

app.UseCors("ApplicationCors");

app.UseHttpsRedirection();

app.UseBlazorFrameworkFiles();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

app.MapRazorPages();
app.MapControllers();
app.MapFallbackToFile("index.html");

app.Run();

1. 中间件顺序错误（核心问题） #

ASP.NET Core中间件的执行顺序直接决定请求是否能被正确处理，你的代码中UseSwagger和UseSwaggerUI放置位置过早，会导致Swagger请求未经过路由匹配就被后续Blazor fallback逻辑拦截，返回404。

需将Swagger相关中间件调整到路由初始化之后、授权中间件之后、端点映射之前，修正后的管道配置如下：

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseWebAssemblyDebugging();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();

app.UseBlazorFrameworkFiles();
app.UseStaticFiles();

app.UseRouting();

app.UseCors("ApplicationCors");

app.UseAuthentication();
app.UseAuthorization();

// 调整Swagger中间件到此处
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "ALPR Dahsboard API");
});

app.MapRazorPages();
app.MapControllers();
app.MapFallbackToFile("index.html");

app.Run();

2. 可选优化：仅在开发环境启用Swagger #

为保障生产环境安全性，建议仅在开发环境加载Swagger中间件：

if (app.Environment.IsDevelopment())
{
    app.UseWebAssemblyDebugging();
    // 仅开发环境启用Swagger
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "ALPR Dahsboard API");
    });
}

3. 验证控制器存在性 #

Swagger依赖ASP.NET Core控制器生成API文档，确保项目中存在标记了[ApiController]和[Route]的控制器类，否则swagger.json会生成空内容，但不会返回404。

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