.NET6 Swagger如何非硬编码配置IncludeXmlComments加载多项目XML注释

核心逻辑：只要确保所有关联项目生成的XML注释文件最终复制到主项目的运行时基目录，就可以统一从该目录加载文件，完全不需要写本地绝对路径，开发、生产环境均可通用。 #

步骤1：配置所有项目的XML生成与输出规则 #

两个项目都需要做如下配置：

• 右键项目 → 选择「属性」→ 进入「生成」 tab → 找到「输出」板块，勾选「XML文档文件」，.NET 6 下默认生成的XML文件名为{项目程序集名}.xml，无需手动修改路径。
• 如果不需要强制要求所有公开成员都编写XML注释，可在同一页面的「抑制警告」输入框中添加1591，避免大量无关编译警告。
• 打开Public项目的.csproj项目文件（可右键项目选择「编辑项目文件」），在<Project>节点下添加如下配置，确保Public项目生成的XML文件会自动复制到引用它的主项目输出目录中：

<ItemGroup>
  <None Update="$(OutputPath)$(AssemblyName).xml">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

主项目MultipleProjectsSwaggerDocs本身开启XML输出后，生成的XML默认就在自身输出目录，不需要额外加复制配置。

步骤2：修改Swagger配置，替换硬编码路径 #

将原来硬编码绝对路径的加载逻辑，改为从运行时基目录AppContext.BaseDirectory读取对应XML文件即可，修改后的AddSwaggerGen配置如下：

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });

    // 加载主项目XML注释
    var mainXmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var mainXmlPath = Path.Combine(AppContext.BaseDirectory, mainXmlFile);
    if (File.Exists(mainXmlPath))
    {
        // 第二个参数传true表示同时加载控制器、接口、模型类上的XML注释
        options.IncludeXmlComments(mainXmlPath, true);
    }

    // 加载Public项目XML注释，无硬编码路径
    var publicXmlPath = Path.Combine(AppContext.BaseDirectory, "Public.xml");
    if (File.Exists(publicXmlPath))
    {
        options.IncludeXmlComments(publicXmlPath, true);
    }
});

说明 #

• 配置中增加了File.Exists判断，避免特定环境下未生成XML文件时导致应用启动报错。
• 该方案完全不依赖本地绝对路径，本地调试、生产发布时，所有关联的XML文件都会随项目编译/发布输出到站点对应的运行目录，不会出现文件找不到的问题。
• 如果后续新增更多需要加载XML注释的引用项目，只需要按步骤1给对应项目开启XML输出、配置复制规则，再在Swagger配置中增加对应XML文件的加载逻辑即可。
• 不建议通过反射遍历所有加载程序集自动加载XML的方案，该方案容易把第三方NuGet包的XML注释也加载到Swagger中，引入无关的文档内容，手动指定需要加载的项目XML文件是最可控、最稳定的实现方式。

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