DotNet7 Blazor WASM模板发布后Swagger无法显示的问题求助

核心问题分析 #

当前配置存在两个关键问题：

• Swagger中间件顺序与Blazor的路由 fallback 逻辑冲突，导致Swagger相关请求被MapFallbackToFile("index.html")捕获
• 未确保Swagger生成的swagger.json文件被包含到发布输出中（生产环境默认不会自动包含）

解决方案 #

方案1：仅在开发环境启用Swagger（推荐用于生产环境不暴露API文档的场景） #

将Swagger的中间件注册逻辑移到开发环境判断块内，避免生产环境加载：

if (app.Environment.IsDevelopment())
{
    app.UseWebAssemblyDebugging();
    // 仅开发环境启用Swagger
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.RoutePrefix = string.Empty;
    });
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

方案2：生产环境启用Swagger（需暴露API文档时使用） #

步骤1：确保Swagger文件被包含到发布输出

编辑Server项目的.csproj文件，添加以下配置：

<PropertyGroup>
  <!-- 生成XML文档（可选，用于Swagger显示接口注释） -->
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

<ItemGroup>
  <!-- 确保swagger.json被复制到发布目录 -->
  <None Update="swagger/v1/swagger.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

步骤2：调整中间件顺序，避免路由冲突

修改Program.cs中的中间件注册顺序，将Swagger逻辑放到UseRouting之后、MapFallbackToFile之前，并修改SwaggerUI的路由前缀，避免与Blazor根路径冲突：

// 保持原有代码不变，直到路由配置部分
app.UseRouting();

// 启用Swagger（生产环境也生效）
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    // 改为指定路由前缀，避免与Blazor的index.html冲突
    c.RoutePrefix = "swagger";
});

// 映射端点
app.MapRazorPages();
app.MapControllers();
// 最后注册Blazor的fallback，确保Swagger路由优先匹配
app.MapFallbackToFile("index.html");

步骤3：验证HTTPS配置

生产环境下app.UseHttpsRedirection()会强制跳转HTTPS，确保你的部署环境配置了有效的HTTPS证书，否则暂时注释该代码块（不建议生产环境长期使用HTTP）。

验证发布 #

1. 发布Server项目（Blazor WASM托管模式下，Client会被自动打包到Server的发布目录中）
2. 访问https://你的部署域名/swagger即可打开Swagger UI
3. 若仍有问题，打开浏览器控制台查看是否有404错误，确认/swagger/v1/swagger.json路径可正常访问

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