FullstackHero Dotnet WebAPI Starter Kit中Swagger文档在IIS部署的解决方案

在基于FullstackHero Dotnet WebAPI Starter Kit开发的项目中，当部署到IIS服务器时，开发者可能会遇到Swagger UI无法正确加载API定义的问题。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题现象分析

当项目部署到IIS后，访问Swagger UI页面时，通常会看到"Failed to load API definition"的错误提示。这种现象在本地开发环境或Docker容器中运行时通常不会出现，但在IIS环境下却频繁发生。

根本原因

这个问题的核心在于IIS服务器对虚拟路径的处理方式与开发环境不同。具体来说：

1. IIS作为反向代理时，会修改请求的基路径(base path)
2. Swagger生成的OpenAPI规范中，服务器(Server)和路径(Path)的定义没有正确反映IIS的虚拟目录结构
3. 默认配置下，Swagger UI尝试从错误的URL端点获取API定义

解决方案

要解决这个问题，我们需要对Startup类或Program类中的Swagger配置进行修改。以下是具体的实现步骤：

1. 修改Swagger配置

在配置Swagger服务时，需要添加对虚拟路径的支持：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API", Version = "v1" });
    
    // 添加对IIS虚拟目录的支持
    c.AddServer(new OpenApiServer()
    {
        Url = "/your-virtual-directory",
        Description = "IIS Virtual Directory"
    });
});

2. 调整Swagger UI中间件

在应用启动配置中，需要确保Swagger UI能够正确处理虚拟路径：

app.UseSwagger(c =>
{
    c.RouteTemplate = "swagger/{documentName}/swagger.json";
    c.PreSerializeFilters.Add((swaggerDoc, httpReq) =>
    {
        if (!httpReq.Headers.ContainsKey("X-Forwarded-Host")) return;
        
        var serverUrl = $"{httpReq.Headers["X-Forwarded-Proto"]}://" +
                       $"{httpReq.Headers["X-Forwarded-Host"]}" +
                       $"{httpReq.Headers["X-Forwarded-Prefix"]}";
        
        swaggerDoc.Servers = new List<OpenApiServer>
        {
            new OpenApiServer { Url = serverUrl }
        };
    });
});

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/your-virtual-directory/swagger/v1/swagger.json", "Your API V1");
    c.RoutePrefix = "swagger";
});

3. 处理反向代理标头

如果应用部署在IIS反向代理后，还需要添加对转发标头的支持：

app.UseForwardedHeaders(new ForwardedHeadersOptions
{
    ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
});

配置说明

1. 虚拟目录路径：将代码中的"/your-virtual-directory"替换为实际IIS中配置的虚拟目录名称
2. 环境适配：上述配置同时兼容开发环境、Docker环境和IIS环境
3. 多环境支持：可以通过环境变量来区分不同环境的配置，实现灵活的部署

验证方案

部署后，可以通过以下步骤验证Swagger是否正常工作：

1. 访问应用URL下的/swagger端点
2. 确认Swagger UI界面正常加载
3. 检查API列表是否正确显示
4. 测试几个API端点，确认请求路径正确

总结

通过上述配置调整，FullstackHero Dotnet WebAPI Starter Kit项目可以无缝地在IIS环境中提供Swagger文档支持。这种解决方案不仅解决了API定义加载失败的问题，还确保了不同部署环境下Swagger UI的一致性表现。开发者可以根据实际项目需求，进一步定制Swagger的配置参数，以获得更好的开发体验。