在.NET 5中使用NSwag时如何显示完整的Swagger界面

解决步骤 #

• 第一步：移除冲突的Swashbuckle依赖
  你当前项目同时安装了NSwag和Swashbuckle.AspNetCore两个Swagger相关组件，二者的API发现逻辑会产生冲突，直接导致控制器接口扫描缺失。你可以通过NuGet包管理器卸载Swashbuckle.AspNetCore全系列包，或在项目目录下执行命令：
  dotnet remove package Swashbuckle.AspNetCore
• 第二步：调整中间件排列顺序
  当前你把NSwag的中间件放在了开发异常页之前，不符合.NET 5的中间件执行顺序规范，会导致静态资源、请求上下文读取异常，需要调整顺序为：开发异常页→NSwag中间件→路由→授权→端点映射。
• 第三步：补充Swagger文档基础配置
  给AddSwaggerDocument方法补充显式的文档配置，确保控制器扫描逻辑正常触发。

修改后完整代码 #

ConfigureServices方法

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    // 补充显式文档配置，指定标题和版本号
    services.AddSwaggerDocument(config =>
    {
        config.Title = "Web API 文档";
        config.Version = "v1";
    });
}

Configure方法

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    // 把NSwag中间件移到异常页之后，路由之前
    app.UseOpenApi();
    app.UseSwaggerUi3();

    app.UseRouting();

    app.UseAuthorization();

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

调整后的项目文件

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="NSwag.AspNetCore" Version="13.11.3" />
  </ItemGroup>
</Project>

完成以上修改后重新生成项目运行，即可在Swagger界面看到完整的WeatherForecastController接口列表。如果后续有自定义控制器，需要确保控制器添加了[ApiController]特性和路由配置，才会被正常扫描到。

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