ASP.NET Core 6中如何配置SwaggerUi3添加URL前缀？

需求说明 #

使用ASP.NET Core 6和NSwag.AspNetCore v13.20.0，需要将SwaggerUI的默认访问URL从https://url/swagger/index.html改为https://url/prefix/swagger/index.html，在Swagger前添加自定义前缀，且UseSwaggerUi已过时，需使用UseSwaggerUi3。

解决方案 #

需要同时配置Swagger文档的生成路径和SwaggerUI的路由前缀，具体修改如下：

1. 修改ConfigureServices中的Swagger文档配置 #

在AddSwaggerDocument中指定swagger元数据文件的路径，并设置文档标识名：

services.AddSwaggerDocument(settings =>
{
    settings.Title = "xxx Api";
    // 设置文档唯一标识，用于后续UI关联
    settings.DocumentName = "v1";
    // 配置swagger json文件的访问路径，带上自定义前缀
    settings.Path = "/prefix/swagger/v1/swagger.json";
});

2. 修改Configure中的中间件配置 #

调整UseOpenApi和UseSwaggerUi3的参数，确保路径与上述配置一致：

// 配置OpenApi中间件的路径，匹配Swagger文档的生成路径
app.UseOpenApi(options =>
{
    options.Path = "/prefix/swagger/v1/swagger.json";
});

// 配置SwaggerUI3的路由前缀和文档源
app.UseSwaggerUi3(options =>
{
    // 设置UI的路由前缀，访问入口变为/prefix/swagger/index.html
    options.RoutePrefix = "prefix/swagger";
    // 添加要加载的swagger文档路由，关联之前设置的文档标识和路径
    options.SwaggerRoutes.Add(new SwaggerUiRoute("v1", "/prefix/swagger/v1/swagger.json"));
});

修改后的完整代码 #

ConfigureServices完整代码

public void ConfigureServices(IServiceCollection services)
{
    _logger.Info("ConfigureServices starting...");

    try
    {
        services.AddControllers(x =>
        {
            x.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
        })
        .AddNewtonsoftJson(x =>
        {
            x.SerializerSettings.TypeNameHandling = Newtonsoft.Json.TypeNameHandling.Objects;
        });

        services.AddTypeSignatureSHA256();

        services.AddHttpClient(nameof(HttpClient)).AddPolicyHandler(GetHttpRetryPolicy());

        services.Configure<IISServerOptions>(options => options.AutomaticAuthentication = false);

        services.AddSwaggerDocument(settings =>
        {
            settings.Title = "xxx Api";
            settings.DocumentName = "v1";
            settings.Path = "/prefix/swagger/v1/swagger.json";
        });
        
        _logger.Info("ConfigureServices ended");
    }
    catch (Exception ex)
    {
        _logger.Error(ex, string.Empty);
        throw;
    }
}

Configure完整代码

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IHostApplicationLifetime appLifeTime)
{
    _logger.Info("Configure starting...");

    try
    {
        RegisterApplicationShutdown(appLifeTime);

        if (env.IsDevelopment())
            app.UseDeveloperExceptionPage();

        app.UseRouting();

        app.UseMiddleware<ExceptionsMiddleware>();
        app.UseMiddleware<HealthChecksUIMiddleware>();
        app.UseAppMetricsPrometheus(new AppMetricsPrometheusSettings { UseSystemUsageCollector = true });
        app.UseMiddleware<AppMetricsRequestsMiddleware>();
        app.UseMiddleware<RequestLoggingMiddleware>();

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

        app.UseOpenApi(options =>
        {
            options.Path = "/prefix/swagger/v1/swagger.json";
        });

        app.UseSwaggerUi3(options =>
        {
            options.RoutePrefix = "prefix/swagger";
            options.SwaggerRoutes.Add(new SwaggerUiRoute("v1", "/prefix/swagger/v1/swagger.json"));
        });

        _logger.Info("Configure ended");
    }
    catch (Exception ex)
    {
        _logger.Error(ex, string.Empty);
        throw;
    }
}

验证 #

配置完成后，访问https://yourdomain/prefix/swagger/index.html即可打开SwaggerUI页面，页面会自动加载https://yourdomain/prefix/swagger/v1/swagger.json中的接口文档。

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