容器环境下如何将NuGet包XML文档添加到Swagger

原创

于 2021-05-25 10:52:00 发布 · 537 阅读

1 ·

CC 4.0 BY-SA版权

文章标签：

#java #docker #linux #python #c++

容器环境下将NuGet包XML文档添加到Swagger

在.NET Core项目开发过程中，为了实现代码复用，我们将可以重复使用的部分拆分成一个个小的NuGet包。这些NuGet包可以在其他系统中复用，这样我们只需要实现系统特定的代码，其余部分的就可以重用了，包括功能、文档等。使用过程中，功能复用没有遇到任何问题，但是文档复用却遇到了问题。我们使用SwashBuckle生成Swagger定义和Swagger UI。Swashbuckle需要XML文档，才能显示控制器和模型的文档说明。不幸的是，Swagger中不能正常显示NuGet包的模型文档说明。

我们可以用在项目文件.csproj的PropertyGroup中添加<GenerateDocumentationFile>true</GenerateDocumentationFile>的方式，将XML文档添加到NuGet包中，然后将XML文档手动拷贝到项目里，作为内容输出。Swagger中就能正常显示NuGet包的模型文档说明了。但是这样做，如果NuGet包版本更新，就需要重新手动拷贝XML文档，感觉不太优雅。是否有更优雅的方式呢？

Google到几篇文章，方案大同小异，不知道可不可行。试试吧！期待可以成功！

实战

我们涉及到两个项目：

ICH.NetCore2.Test.WebApi：ASP.NET Core WebApi 主项目
ICH.Common：可重用的公共组件NuGet包

我们按照以下几个步骤分布实施。

1、设置.csproj文件构建NuGet包时包含XML文档

ICH.Common的项目文件.csproj的PropertyGroup中添加<GenerateDocumentationFile>true</GenerateDocumentationFile>，作用是设置.csproj文件构建NuGet包时包含XML文档。

<PropertyGroup>
      <TargetFramework>netstandard2.0</TargetFramework>
      <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

2、定义从NuGet包文件夹的根目录到XML文档所在位置的相对路径

ICH.NetCore2.Test.WebApi的项目文件.csproj的PackageReference中添加<CopyToOutputDirectory>lib\netstandard2.0\*.xml</CopyToOutputDirectory>，作用是定义从NuGet包文件夹的根目录到XML文档所在位置的相对路径。

<ItemGroup>
      <PackageReference Include="ICH.Common" Version="$(ICHCoreFXVersion)">
             <CopyToOutputDirectory>lib\netstandard2.0\*.xml</CopyToOutputDirectory>
      </PackageReference>
</ItemGroup>

在.NET Core中，我们的NuGet包位于：%USERPROFILE%\.nuget\packages\{PackageName}\{PackageVersion}
XML文档文件位于：%USERPROFILE%\.nuget\packages\{PackageName}\{PackageVersion}\lib\netcoreapp2.1\{PackageName}.xml

3、设置构建后从NuGet包中复制XML文档

ICH.NetCore2.Test.WebApi的项目文件.csproj添加<Target Name="AfterTargetsBuild" AfterTargets="Build">，作用是设置构建后从NuGet包中复制XML文档。

<Target Name="AfterTargetsBuild" AfterTargets="Build">
      <ItemGroup>
             <PackageReferenceFiles 
                    Condition="%(PackageReference.CopyToOutputDirecto