根據註釋生成xml和從nuget包中複製xml顯示到swagger

生成xml到輸出目錄

從註釋生成xml

在要生成xml的項目的csproj中添加如下代碼, 其中的MyApplication.xml 記得換成程序集的名稱,也就是項目名稱.xml. 比如該項目叫做Abp.Application, 則xml名爲 Abp.Application.xml

  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
    <DocumentationFile>bin\Debug\MyApplication.xml</DocumentationFile>
    <OutputPath>bin\Debug\</OutputPath>
  </PropertyGroup>

  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
    <DocumentationFile>bin\Release\MyApplication.xml</DocumentationFile>
    <OutputPath>bin\Release\</OutputPath>
  </PropertyGroup>

然後生成就會將xml拷貝到輸出目錄了

從nuget包中拷貝xml到輸出目錄

如果xml在nuget包中, 則需要修改引用nuget的配置.
在csproj中,假設原本引用的是<PackageReference Include="Abp.Application" Version="6.0.0" />, 且Abp.Application.xml在nuget包中的路徑爲lib/net5.0/Abp.Application.xml ,可以在$HOME/.nuget/包名/下查看xml所在路徑. 如果該包的目標平臺是.net 5,則路徑就爲lib/net5.0/xxx.xml, 如果目標平臺爲.netstandard 2.0,則路徑爲lib/netstandard2.0/*.xml,以此類推
最後需要在此中間添加其路徑<CopyToOutputDirectory>lib/net5.0/*.xml</CopyToOutputDirectory>
即

   ​<PackageReference Include="Abp.Application" Version="6.0.0" >
     ​<CopyToOutputDirectory>lib/net5.0/*.xml</CopyToOutputDirectory>
   ​</PackageReference>

需要注意的是沒有顯示配置拷貝xml的nuget包,也就是依賴的包是不會自動拷貝xml的,需要上面一樣手動添加引用配置xml拷貝纔行. 比如接口註釋在Application, dto註釋在Application.Share,那需要再加一個Application.Share的引用並配置xml拷貝.

然後添加構建後拷貝操作, build和publish都需要. linux下構建需要設置環境變量NUGET_XMLDOC_MODE=none, 在官方文檔中有解釋NUGET_XMLDOC_MODE的作用

<Target Name="CopyXMLFromPackagesForBuild" AfterTargets="Build">
	<ItemGroup>
		<PackageReferenceFiles Condition="%(PackageReference.CopyToOutputDirectory) != ''" Include="$(NugetPackageRoot)$([MSBuild]::Escape('%(PackageReference.Identity)').ToLower())/%(PackageReference.Version)/%(PackageReference.CopyToOutputDirectory)" />
	</ItemGroup>
	<Copy SourceFiles="@(PackageReferenceFiles)" DestinationFolder="$(OutDir)" />
</Target>

<Target Name="CopyXMLFromPackagesForPublish" BeforeTargets="PrepareForPublish">
	<ItemGroup>
		<PackageReferenceFiles Condition="%(PackageReference.CopyToOutputDirectory) != ''" Include="$(NugetPackageRoot)$([MSBuild]::Escape('%(PackageReference.Identity)').ToLower())/%(PackageReference.Version)/%(PackageReference.CopyToOutputDirectory)" />
	</ItemGroup>
	<Copy SourceFiles="@(PackageReferenceFiles)" DestinationFolder="$(PublishDir)" />
</Target>

完整代碼如下

  <ItemGroup>
    <PackageReference Include="Abp.Application" Version="6.0.0" >
      <CopyToOutputDirectory>lib/net5.0/*.xml</CopyToOutputDirectory>
    </PackageReference>
  </ItemGroup>
<Target Name="CopyXMLFromPackagesForBuild" AfterTargets="Build">
	<ItemGroup>
		<PackageReferenceFiles Condition="%(PackageReference.CopyToOutputDirectory) != ''" Include="$(NugetPackageRoot)$([MSBuild]::Escape('%(PackageReference.Identity)').ToLower())/%(PackageReference.Version)/%(PackageReference.CopyToOutputDirectory)" />
	</ItemGroup>
	<Copy SourceFiles="@(PackageReferenceFiles)" DestinationFolder="$(OutDir)" />
</Target>

<Target Name="CopyXMLFromPackagesForPublish" BeforeTargets="PrepareForPublish">
	<ItemGroup>
		<PackageReferenceFiles Condition="%(PackageReference.CopyToOutputDirectory) != ''" Include="$(NugetPackageRoot)$([MSBuild]::Escape('%(PackageReference.Identity)').ToLower())/%(PackageReference.Version)/%(PackageReference.CopyToOutputDirectory)" />
	</ItemGroup>
	<Copy SourceFiles="@(PackageReferenceFiles)" DestinationFolder="$(PublishDir)" />
</Target>

swagger添加xml顯示註釋

加載拷貝到輸出目錄的xml,在services.AddSwaggerGen的方法中添加如下代碼

                    //遍歷所有xml並加載
                    var binXmlFiles =
                        new DirectoryInfo(AppDomain.CurrentDomain.BaseDirectory.IsNullOrEmpty()
                            ? Path.GetDirectoryName(System.Reflection.Assembly.GetEntryAssembly().Location)
                            : AppDomain.CurrentDomain.BaseDirectory).GetFiles("*.xml", SearchOption.TopDirectoryOnly);
                    foreach (var filePath in binXmlFiles.Select(item => item.FullName))
                    {
                        options.IncludeXmlComments(filePath, true);
                    }

完整示例,僅包含加載xml

services.AddSwaggerGen(options=>
{
                    //遍歷所有xml並加載
                    var binXmlFiles =
                        new DirectoryInfo(AppDomain.CurrentDomain.BaseDirectory.IsNullOrEmpty()
                            ? Path.GetDirectoryName(System.Reflection.Assembly.GetEntryAssembly().Location)
                            : AppDomain.CurrentDomain.BaseDirectory).GetFiles("*.xml", SearchOption.TopDirectoryOnly);
                    foreach (var filePath in binXmlFiles.Select(item => item.FullName))
                    {
                        options.IncludeXmlComments(filePath, true);
                    }
}