根据注释生成xml和从nuget包中复制xml显示到swagger

生成xml到输出目录

从注释生成xml

在要生成xml的项目的csproj中添加如下代码, 生成的xml名称为项目名称.xml. 比如该项目叫做Abp.Application, 则xml名为 Abp.Application.xml

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

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

然后生成就会将xml拷贝到输出目录了

从nuget包中拷贝xml到输出目录

linux下构建需要设置环境变量NUGET_XMLDOC_MODE=none, 在官方文档中有解释NUGET_XMLDOC_MODE的作用

然后修改csproj, 添加如下代码, 构建和发布都会将nuget包中以Abp开头的xml和pdb文件拷贝到输出目录了, 如果是要拷贝所有包的xml和pdb都拷贝过去可以把Abp*.xml改为%(Reference.Filename).xml, pdb文件同理.

  <Target Name="CopyReferenceFilesBuild" BeforeTargets="Build">
    <ItemGroup>
      <ReferenceFiles Include="%(Reference.RelativeDir)Abp*.xml;%(Reference.RelativeDir)Abp*.pdb" />
    </ItemGroup>

    <Message Text="Copying reference files to $(OutputPath)" Importance="High" />
    <Copy SourceFiles="@(ReferenceFiles)" DestinationFolder="$(OutputPath)" Condition="Exists('%(RootDir)%(Directory)%(Filename)%(Extension)')" />
  </Target>

  <Target Name="CopyReferenceFilesPublish" BeforeTargets="PrepareForPublish">
    <ItemGroup>
      <ReferenceFiles Include="%(Reference.RelativeDir)Abp*.xml;%(Reference.RelativeDir)Abp*.pdb" />
    </ItemGroup>

    <Message Text="Copying reference files to $(OutputPath)" Importance="High" />
    <Copy SourceFiles="@(ReferenceFiles)" DestinationFolder="$(PublishDir)" Condition="Exists('%(RootDir)%(Directory)%(Filename)%(Extension)')" />
  </Target>

swagger添加xml显示注释

加载拷贝到输出目录的xml,在services.AddSwaggerGen的方法中添加如下代码.

GetFiles("*.xml", SearchOption.TopDirectoryOnly)

如果是拷贝了所有的xml,而只想加载以Abp开头的xml文件则可以把.xml改为Abp.xml

                    //遍历所有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);
                    }

完整示例

services.AddSwaggerGen(options=>
{
                    options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
                    options.DocInclusionPredicate((docName, description) => true);
                    options.CustomSchemaIds(type => type.ToString());
                    //遍历所有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);
                    }
}