如何将NuGet包中的SDK.xml导入Web API并配置Swagger？

1. 确认NuGet包的XML文件打包状态 #

你的SDK项目已设置<GenerateDocumentationFile>True</GenerateDocumentationFile>，默认NuGet会自动把生成的XML文件打包到lib/netstandard2.0目录（和DLL同路径）。既然你已在本地缓存找到该文件，这一步可跳过；若后续仍有问题，可在SDK的csproj中显式添加XML打包配置：

<ItemGroup>
  <DocumentationFile Include="$(OutputPath)$(AssemblyName).xml" />
  <None Include="$(OutputPath)$(AssemblyName).xml">
    <Pack>True</Pack>
    <PackagePath>lib/netstandard2.0</PackagePath>
  </None>
</ItemGroup>

2. 配置Web API复制SDK的XML文件 #

在你的net6.0 Web API项目的csproj中添加以下配置，确保SDK的XML文件被复制到项目输出目录：

方式一：硬编码路径（适合固定版本） #

<ItemGroup>
  <None Include="$(UserProfile)\.nuget\packages\你的SDK包名\4.2.0\lib\netstandard2.0\SDK.xml">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <Link>SDK.xml</Link>
  </None>
</ItemGroup>

替换你的SDK包名为实际的NuGet包名称即可。

方式二：自动匹配依赖（推荐，适配版本变更） #

<Target Name="CopySdkXml" AfterTargets="ResolveReferences">
  <ItemGroup>
    <SdkXmlFiles Include="@(ReferenceCopyLocalPaths)" Condition="'%(Extension)' == '.xml' and '%(ReferenceCopyLocalPaths.NuGetPackageId)' == '你的SDK包名'" />
  </ItemGroup>
  <Copy SourceFiles="@(SdkXmlFiles)" DestinationFolder="$(OutputPath)" SkipUnchangedFiles="true" />
</Target>

这种方式会自动识别依赖包的XML文件，无需硬编码路径和版本号。

3. 在Swagger中加载XML文件 #

修改Web API项目的Program.cs（老模板为Startup.cs）中的Swagger配置代码，添加对SDK XML文件的引用：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSwaggerGen(c =>
{
    // 加载当前项目的XML文档（可选，若需要显示自身API注释）
    var currentXmlPath = Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml");
    if (File.Exists(currentXmlPath))
    {
        c.IncludeXmlComments(currentXmlPath);
    }

    // 加载SDK的XML文档
    var sdkXmlPath = Path.Combine(AppContext.BaseDirectory, "SDK.xml");
    if (File.Exists(sdkXmlPath))
    {
        // 仅加载模型注释，排除控制器相关内容
        c.IncludeXmlComments(sdkXmlPath, includeControllerXmlComments: false);
    }
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.Run();

4. 验证结果 #

重新构建并启动Web API，访问Swagger页面，检查模型的注释是否正常显示。若未生效，可排查以下点：

• 确认SDK的XML文件内确实包含模型注释（直接打开XML文件查看）
• 确认XML文件已被复制到Web API的输出目录（bin/Debug/net6.0下）
• 确认Swagger配置中的文件名与实际文件名完全一致

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