部署测试服务器后Swagger UI无法渲染双文档定义问题

问题场景 #

为API搭建了两个独立Swagger页面：

• 内部使用的「Full」全端点页面
• 外部用户使用的「Limited」页面

通过以下方式实现分组：

• 给外部端点添加装饰器：[ApiExplorerSettings(GroupName = "Limited")]
• 移除不需要暴露的端点的[ApiExplorerSettings(IgnoreApi = true)]装饰器
• 新增两个不同标题的SwaggerDoc，并通过以下代码配置UI：

app.Map("/swagger/full", fullApp =>
{
    fullApp.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/Full/swagger.json", "Full API Documentation");
        c.RoutePrefix = ""; // UI 托管在 /swagger/full
    });
});

// 有限权限API的Swagger UI
app.Map("/swagger/limited", limitedApp =>
{
    limitedApp.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/Limited/swagger.json", "Limited API Documentation");
        c.RoutePrefix = ""; // UI 托管在 /swagger/limited
    });
});

本地运行完全正常，但部署到测试服务器后，Swagger UI提示「无法渲染定义」，尝试更新Swashbuckle包、切换OpenAPI版本、清除缓存均无效，恢复单页面部署则正常。

核心原因分析 #

部署环境下的路径解析逻辑和本地不同，主要是Swagger UI请求swagger.json时的路径错误：

• 当UI托管在/swagger/full（RoutePrefix为空）时，直接使用绝对路径/swagger/Full/swagger.json在部分部署场景（比如反向代理、子路径部署）下会被解析为错误的地址，导致404无法获取swagger.json文件。
• 另外可能存在SwaggerDoc未正确注册，导致对应分组的swagger.json未生成。

解决方案 #

1. 确保SwaggerDoc正确注册 #

在AddSwaggerGen中必须为两个分组都配置SwaggerDoc：

services.AddSwaggerGen(c =>
{
    // 注册Full分组的文档
    c.SwaggerDoc("Full", new OpenApiInfo 
    { 
        Title = "Full API Documentation", 
        Version = "v1" 
    });
    // 注册Limited分组的文档
    c.SwaggerDoc("Limited", new OpenApiInfo 
    { 
        Title = "Limited API Documentation", 
        Version = "v1" 
    });

    // 可选：添加注释支持等其他配置
    // var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    // var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    // c.IncludeXmlComments(xmlPath);
});

2. 使用相对路径配置SwaggerEndpoint #

修改UI配置中的SwaggerEndpoint为相对路径，适配当前UI的托管路径：

app.Map("/swagger/full", fullApp =>
{
    fullApp.UseSwaggerUI(c =>
    {
        // 从/swagger/full向上一级，请求/swagger/Full/swagger.json
        c.SwaggerEndpoint("../Full/swagger.json", "Full API Documentation");
        c.RoutePrefix = "";
    });
});

app.Map("/swagger/limited", limitedApp =>
{
    limitedApp.UseSwaggerUI(c =>
    {
        // 从/swagger/limited向上一级，请求/swagger/Limited/swagger.json
        c.SwaggerEndpoint("../Limited/swagger.json", "Limited API Documentation");
        c.RoutePrefix = "";
    });
});

3. 确保UseSwagger中间件正确配置 #

在Map之前先配置UseSwagger，确保所有分组的swagger.json都能被正常访问：

// 先启用Swagger文档生成，确保所有分组的swagger.json都能被获取
app.UseSwagger(c =>
{
    // 保持默认的路由模板，确保{documentName}能正确匹配分组名
    c.RouteTemplate = "swagger/{documentName}/swagger.json";
});

// 再配置两个UI的Map路由
app.Map("/swagger/full", fullApp =>
{
    // ... 同上
});

app.Map("/swagger/limited", limitedApp =>
{
    // ... 同上
});

4. 适配部署环境的子路径/反向代理 #

如果API部署在子路径下（比如https://example.com/api/），需要先配置PathBase：

// 替换为实际的部署子路径
app.UsePathBase("/api");

此时SwaggerEndpoint的路径需要再次调整，比如：

c.SwaggerEndpoint("../../Full/swagger.json", "Full API Documentation");

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