.NET Core 3.1 API部署IIS子站点Swagger异常求助

针对你的场景（Web API作为IIS主站点Site1的子站点，访问路径https://site1/api），以下是经过验证的配置方案：

核心配置步骤 #

1. 配置Swagger文档的BasePath #

在ConfigureServices方法中，添加文档过滤器以适配子站点的虚拟路径，确保Swagger生成的接口地址正确：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public void ConfigureServices(IServiceCollection services)
{
    // 其他服务配置...
    
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Loyalty API", Version = "v1" });
        // 添加文档过滤器，指定子站点虚拟路径
        c.DocumentFilter<BasePathFilter>();
    });
}

// 定义BasePathFilter类，用于修正Swagger文档的服务器地址
public class BasePathFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 对应IIS子站点的虚拟路径/api
        swaggerDoc.Servers.Add(new OpenApiServer { Url = "/api" });
    }
}

2. 配置Swagger中间件适配子站点路径 #

在Configure方法中，设置路径基并调整Swagger UI的端点和路由前缀：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 其他中间件配置（如异常处理、静态文件等）...
    
    // 启用路径基，匹配IIS子站点的虚拟路径
    app.UsePathBase("/api");

    // 启用Swagger JSON生成
    app.UseSwagger();

    // 配置Swagger UI
    app.UseSwaggerUI(c =>
    {
        // 使用相对路径指向Swagger JSON，自动适配子站点路径
        c.SwaggerEndpoint("./swagger/v1/swagger.json", "Loyalty API");
        // 设置路由前缀为空，使Swagger UI直接在子站点根路径（https://site1/api）访问
        c.RoutePrefix = string.Empty;
    });

    // 路由配置...
    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

3. 本地调试适配（可选） #

修改launchSettings.json，模拟子站点路径，确保本地调试和部署环境行为一致：

{
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:50473/api"
    },
    "YourApiProjectName": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:50473/api"
    }
  }
}

IIS配置验证 #

确保以下IIS配置正确：

• 子站点的应用程序池设置为无托管代码集成管道
• 子站点物理路径指向Web API发布后的文件目录
• 确认ASP.NET Core 3.1托管捆绑包已正确安装
• 检查IIS请求筛选规则，未阻止.json和.html文件的访问

常见问题排查 #

• 如果仍出现404：检查UsePathBase是否在UseSwagger之前调用，中间件顺序会影响路径解析
• 如果Swagger UI超链接异常：确保BasePathFilter已正确设置服务器地址，避免硬编码绝对路径

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