.NET Core 3.1 Web API配置Swagger报错问题咨询

常见故障点及修复方法 #

1. 检查Nuget包版本兼容性 #

.NET Core 3.1 仅兼容 5.x版本的Swashbuckle.AspNetCore系列包，6.x及以上版本仅支持.NET 5+，安装高版本会直接导致运行异常。

• 卸载项目中已安装的高版本Swashbuckle相关包，安装指定稳定版：

Install-Package Swashbuckle.AspNetCore -Version 5.6.3

该包会自动依赖安装Swagger、SwaggerGen、SwaggerUI三个核心组件，无需单独安装。

2. 修复中间件管道顺序 #

当前配置的中间件顺序不符合.NET Core 3.1的路由规则，Swagger中间件必须放在UseRouting()之后、UseEndpoints()之前，否则路由映射不生效，无法访问swagger.json文件。
修正后的Configure方法代码参考：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 其他前置中间件（异常处理、静态文件、HSTS等）保留原有配置
    
    app.UseRouting();

    // Swagger中间件移动到UseRouting之后
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Core Library");
        c.RoutePrefix = string.Empty;
    });

    // 授权类中间件（如有）放在这个位置，例如app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

3. 补全XML注释配置（如开启了XML文档输出） #

如果项目在属性-生成配置中勾选了「XML文档文件」，必须在SwaggerGen配置中添加XML文件加载逻辑，否则会因文件找不到抛出异常。
修正后的AddSwagger方法代码参考：

private void AddSwagger(IServiceCollection services)
{
    services.AddSwaggerGen(options =>
    {
        var groupName = "v1";
        options.SwaggerDoc(groupName, new OpenApiInfo
        { 
            Title = "Core Library", 
            Version = "v1"
        });

        // 加载XML注释文件
        var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
        options.IncludeXmlComments(xmlFilePath, true);
    });
}

注意使用上述代码需要额外引入System.Reflection和System.IO命名空间。

4. 其他排查项 #

• 确认API控制器都添加了[ApiController]和[Route]特性，没有公开路由的控制器不会被Swagger识别，无有效API端点时也会导致Swagger生成失败。
• 启动项目后直接访问/swagger/v1/swagger.json路径，若返回500错误可查看Visual Studio输出窗口的异常堆栈，可直接定位具体错误原因（如程序集加载失败、过滤器冲突等）。

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