如何让Swagger UI加载多个.csproj文件生成的XML注释

问题根源 #

你的Swagger配置仅加载了**主项目（Proj1）**的XML注释文件，其他4个项目的XML文件未被纳入Swagger的注释加载逻辑，因此只有Proj1的注释能在UI中显示。

解决方案 #

需要将所有带有XML注释的项目对应的.xml文件都添加到Swagger配置中，以下是两种实现方式：

方式1：自动遍历加载所有依赖项目的XML注释

适合项目数量较多的场景，自动扫描主项目引用的所有程序集对应的XML文件：

修改Startup.cs中的AddSwaggerGen配置：

builder.Services.AddSwaggerGen(config => {
    config.SwaggerDoc(appVersion, new OpenApiInfo {
        Title = "Proj1 API",
        Version = appVersion,
        Description = "REST API for control of Proj1 data"
    });
    config.SchemaFilter<ResourceSchemaFilter>();
    config.OrderActionsBy(a => $"{a.RelativePath}_{a.HttpMethod}");
    config.CustomSchemaIds(x => x.FullName);

    // 加载当前主项目的XML注释
    var executingAssembly = Assembly.GetExecutingAssembly();
    var executingXmlPath = Path.Combine(AppContext.BaseDirectory, $"{executingAssembly.GetName().Name}.xml");
    config.IncludeXmlComments(executingXmlPath);

    // 遍历所有引用的项目，加载对应的XML注释
    foreach (var referencedAssembly in executingAssembly.GetReferencedAssemblies())
    {
        try
        {
            var assembly = Assembly.Load(referencedAssembly);
            var xmlPath = Path.Combine(AppContext.BaseDirectory, $"{assembly.GetName().Name}.xml");
            if (File.Exists(xmlPath))
            {
                config.IncludeXmlComments(xmlPath);
            }
        }
        catch (FileNotFoundException)
        {
            // 忽略找不到的程序集，可根据需要添加日志
            continue;
        }
    }
});

方式2：手动指定加载目标项目的XML注释

适合项目数量少、需精准控制加载范围的场景，手动列出每个项目的XML文件路径：

修改Startup.cs中的AddSwaggerGen配置：

builder.Services.AddSwaggerGen(config => {
    config.SwaggerDoc(appVersion, new OpenApiInfo {
        Title = "Proj1 API",
        Version = appVersion,
        Description = "REST API for control of Proj1 data"
    });
    config.SchemaFilter<ResourceSchemaFilter>();
    config.OrderActionsBy(a => $"{a.RelativePath}_{a.HttpMethod}");
    config.CustomSchemaIds(x => x.FullName);

    // 加载主项目Proj1的注释
    var proj1Xml = Path.Combine(AppContext.BaseDirectory, "Proj1.xml");
    config.IncludeXmlComments(proj1Xml);

    // 加载Proj2的注释
    var proj2Xml = Path.Combine(AppContext.BaseDirectory, "Proj2.xml");
    if (File.Exists(proj2Xml)) config.IncludeXmlComments(proj2Xml);

    // 加载Proj3的注释
    var proj3Xml = Path.Combine(AppContext.BaseDirectory, "Proj3.xml");
    if (File.Exists(proj3Xml)) config.IncludeXmlComments(proj3Xml);

    // 同理添加Proj4、Proj5的XML路径
});

额外配置优化（确保XML文件复制到主输出目录） #

修改Directory.Build.props，明确指定XML文件的输出路径，并确保被复制到主项目的输出目录：

<PropertyGroup Condition="'$(Configuration)'=='Debug'">
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <!-- 指定XML文件输出到项目输出目录 -->
    <DocumentationFile>$(OutputPath)$(AssemblyName).xml</DocumentationFile>
    <!-- 确保XML文件被复制到引用它的主项目输出目录 -->
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <NoWarn>$(NoWarn);1570;1572;1573;1587;1591;1701;1702;1705;1591</NoWarn>
</PropertyGroup>

验证步骤 #

1. 重新生成解决方案，确认所有项目的.xml文件都出现在主项目的bin/Debug目录下
2. 启动应用，打开Swagger UI，检查各项目的接口和模型注释是否正常显示

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