如何在Swagger文档中合并Web API与模型项目的XML注释

不需要手动把多个项目的XML注释合并为单个物理文件，Swashbuckle（ASP.NET Core默认的Swagger组件）原生支持同时加载多个XML注释源，配置步骤如下：

• 第一步：开启所有相关项目的XML文档生成
  右键Web API主项目、独立模型项目，依次打开「属性→生成→输出」，勾选「XML文档文件」，两个项目的XML文件名保持和自身程序集名一致即可，不需要手动改路径；同时建议取消1591号编译警告的提示，避免未给公共成员写注释时弹出大量编译警告。

• 第二步：修改Swagger配置，加载多份XML文件
  打开Web API项目的Program.cs，替换原有单XML加载的逻辑，同时引入主项目和模型项目的注释文件，参考代码如下：

using System.Reflection;

// 其他服务注册逻辑...
builder.Services.AddSwaggerGen(options =>
{
    // 加载当前Web API主项目的XML注释
    var mainAssemblyXmlPath = Path.Combine(
        AppContext.BaseDirectory, 
        $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"
    );
    options.IncludeXmlComments(mainAssemblyXmlPath, includeControllerXmlComments: true);

    // 加载独立模型项目的XML注释，推荐通过模型项目中的公共类获取程序集，避免写错程序集名
    // 将示例类替换为你模型项目中任意一个公开类即可
    var modelAssembly = typeof(YourModelNamespace.任意模型类).Assembly;
    var modelAssemblyXmlPath = Path.Combine(
        AppContext.BaseDirectory, 
        $"{modelAssembly.GetName().Name}.xml"
    );
    options.IncludeXmlComments(modelAssemblyXmlPath);

    // 后续如果有其他类库项目需要加载注释，重复上述逻辑添加对应XML路径即可
});

• 第三步：配置XML文件复制规则，避免运行时找不到文件
  右键Web API项目的依赖项中对模型项目的引用，打开属性将「复制本地」设置为True，确保模型项目生成的XML文件会被复制到Web API的运行目录。如果需要兼容发布场景，也可以直接在模型项目的.csproj文件中添加生成后事件，自动将XML复制到主项目输出目录：

<Target Name="CopyModelXmlToApiOutput" AfterTargets="Build">
  <Copy 
    SourceFiles="$(OutputPath)$(AssemblyName).xml" 
    DestinationFolder="$(SolutionDir)你的WebAPI项目目录名\bin\$(Configuration)\$(TargetFramework)\" 
  />
</Target>

如果你有特殊需求必须生成单个物理XML文件，可以在生成后事件中编写脚本，将多个XML的<members>节点内容合并到同一个XML文件中，再让Swagger加载这个合并后的文件即可。但这种方案需要额外处理XML节点冲突、文件覆盖逻辑，维护成本远高于直接加载多份XML的方案，非必要不推荐使用。

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