NSwag无法从引用程序集的代码注释生成OpenAPI描述

我有一个.NET API项目，引用了通过NuGet发布的DataAccess项目包，该包包含程序集.dll和对应的XML文档文件。使用NSwag生成OpenAPI的swagger.json时，API项目内的类和属性能正常从代码注释生成描述，但DataAccess项目中的类型和属性没有任何描述。已经尝试在Startup.cs中配置ResolveExternalXmlDocumentation，但没有效果。

解决步骤 #

• 确保NuGet包中的XML文件被正确复制到API项目输出目录
  在DataAccess项目的.csproj文件中，需要明确配置生成并打包XML文档：

  <PropertyGroup>
    <!-- 开启XML文档生成 -->
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  </PropertyGroup>
  <ItemGroup>
    <!-- 将XML文件包含到NuGet包中，安装时复制到输出目录 -->
    <None Include="$(OutputPath)$(AssemblyName).xml" Pack="true" PackagePath="lib\$(TargetFramework)" />
  </ItemGroup>
  

  安装NuGet包后，检查API项目的bin/Debug或bin/Release目录，确认DataAccess的XML文件存在。

• 显式配置NSwag加载外部XML文档
  仅开启ResolveExternalXmlDocumentation不足以加载外部程序集的XML，需要手动指定XML文件路径。在API项目的Startup.cs（.NET 6+则是Program.cs）中修改NSwag配置：

  services.AddOpenApiDocument(settings =>
  {
      settings.Title = "API文档";
      settings.ResolveExternalXmlDocumentation = true;
      // 替换为DataAccess程序集的XML文件名（不带.dll后缀）
      var dataAccessXmlPath = Path.Combine(AppContext.BaseDirectory, "DataAccessAssembly.xml");
      if (File.Exists(dataAccessXmlPath))
      {
          settings.XmlDocumentationPaths.Add(dataAccessXmlPath);
      }
  });
  

• 验证XML文档的正确性
  打开DataAccess项目生成的XML文件，确认类和属性的注释已正确生成，比如：

  <member name="T:YourNamespace.DataAccessClass">
    <summary>DataAccess类的业务描述</summary>
  </member>
  <member name="P:YourNamespace.DataAccessClass.Property1">
    <summary>Property1的具体说明</summary>
  </member>
  

  如果XML中没有这些内容，检查DataAccess项目的生成设置：右键项目→属性→生成→输出，勾选“XML文档文件”。

• 清理并重新生成解决方案
  清理API和DataAccess项目的输出目录，重新生成整个解决方案，确保最新的XML文件被复制到API项目的输出路径。

示例对比 #

API项目类在swagger.json中的正常输出： #

"ApiClass": {
    "type": "object",
    "description": "Hello!", // 从代码注释生成
    "additionalProperties": false,
    "properties": {
      "property1": {
        "type": "string",
        "description": "Hello back!", // 从代码注释生成
        "nullable": true
      }
    }
}

DataAccess项目类无描述的问题输出： #

"DataAccessClass": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "property1": {
        "type": "integer",
        "format": "int32"
      },
      "property2": {
        "type": "string",
        "nullable": true
      }
    }
}

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