.NET 8 + Swashbuckle：K8s子路径下Swagger Try it out URL重写问题

针对.NET 8 + Swashbuckle.AspNetCore 6.8.1在K8s子路径部署场景下，Swagger UI的"Try it out"请求缺失子路径的问题，以下是可行的解决方法：

核心问题分析 #

你之前的配置失效，大概率是因为K8s Ingress做了路径重写——Ingress将https://app.example.org/book-import/swagger/...转发给应用时，可能已经去掉了/book-import前缀，导致应用收到的请求路径是/swagger/...，因此你的PreSerializeFilters中的!httpReq.Path.Value.StartsWith("/swagger")条件无法触发，日志也不会输出。

另外，.NET默认不信任反向代理传递的X-Forwarded-*系列头，即使Ingress设置了X-Forwarded-Prefix（用于告知应用它的子路径），应用也无法正确读取。

解决方案一：利用Ingress的X-Forwarded-Prefix头（推荐） #

大多数K8s Ingress控制器（如NGINX Ingress）会自动添加X-Forwarded-Prefix头，我们可以通过配置应用信任该头，再在Swagger中读取这个值来设置Server URL：

步骤1：配置ForwardedHeaders #

在Program.cs中，添加反向代理头信任配置（必须在app.UseRouting()之前调用）：

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto | ForwardedHeaders.XForwardedPrefix;
    // 添加K8s集群内部IP或Ingress控制器IP到信任列表，根据实际集群调整
    options.KnownProxies.Add(IPAddress.Parse("10.0.0.0/8"));
});

// 在路由之前启用ForwardedHeaders
app.UseForwardedHeaders();

步骤2：修改Swagger PreSerializeFilters配置 #

更新MapSwaggerDefaults的配置，优先读取X-Forwarded-Prefix，同时兼容本地开发场景：

app.MapSwaggerDefaults(builder.Configuration, swaggerOptions: options =>
{
    options.PreSerializeFilters.Add((swagger, httpReq) =>
    {
        var logger = app.Services.GetRequiredService<ILogger<Program>>();
        logger.LogInformation("X-Forwarded-Prefix: {Prefix}", httpReq.Headers["X-Forwarded-Prefix"]);
        logger.LogInformation("Request Path: {Path}", httpReq.Path.Value);

        // 优先从K8s Ingress传递的头获取子路径
        if (httpReq.Headers.TryGetValue("X-Forwarded-Prefix", out var prefix) && !string.IsNullOrEmpty(prefix))
        {
            swagger.Servers = new List<OpenApiServer> { new OpenApiServer { Url = prefix } };
        }
        // 本地开发场景：从请求路径中提取子路径
        else if (httpReq.Path.Value != null)
        {
            var basePathIndex = httpReq.Path.Value.IndexOf("/swagger", StringComparison.OrdinalIgnoreCase);
            if (basePathIndex > 0)
            {
                var basePath = httpReq.Path.Value.Substring(0, basePathIndex);
                swagger.Servers = new List<OpenApiServer> { new OpenApiServer { Url = basePath } };
            }
        }
    });
});

解决方案二：环境变量手动指定子路径 #

如果你的Ingress未配置X-Forwarded-Prefix，可以给每个服务设置独立的环境变量来指定Swagger的基础路径：

步骤1：代码中读取环境变量 #

在Program.cs的AddSwaggerGen中添加配置：

var swaggerBasePath = Environment.GetEnvironmentVariable("ASPNETCORE_SWAGGER_BASEPATH") ?? string.Empty;

builder.Services.AddSwaggerGen(o =>
{
    if (!string.IsNullOrEmpty(swaggerBasePath))
    {
        o.SwaggerGeneratorOptions.Servers = new List<OpenApiServer> { new OpenApiServer { Url = swaggerBasePath } };
    }
});

步骤2：K8s Deployment中设置环境变量 #

为每个服务的Deployment添加对应环境变量：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: book-import-service
spec:
  template:
    spec:
      containers:
      - name: book-import-service
        image: your-image:tag
        env:
        - name: ASPNETCORE_SWAGGER_BASEPATH
          value: "/book-import"

验证方法 #

部署后访问Swagger UI，查看页面顶部的"Servers"下拉框，确认显示的URL包含对应的子路径（如/book-import），此时"Try it out"发起的请求会自动带上该前缀。

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