如何在ASP.NET Core的Swagger中包含XML注释文件

Question

我需要Swagger生成包含UI的API文档来测试操作。

在我的项目中使用ASP.NET时，将生成deps XML文件，一切正常，如下所示：

但是，当我在项目中使用ASP.NET Core时，不会生成deps XML文件。它只是生成我的项目注释XML文件，如下所示：

当我将项目部署到IIS时，项目XML不在部署文件列表中。

Answer 1

我用这种方式来注册XML文件：

  foreach (var filePath in System.IO.Directory.GetFiles(Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location)), "*.xml"))
                {
                    try
                    {
                        c.IncludeXmlComments(filePath);
                    }
                    catch (Exception e)
                    {
                        Console.WriteLine(e);
                    }
                }

Answer 2

对于 .Net Core 3.1 和 NuGet xml 文件，我将其添加到项目文件中：

<Project>

  <!-- Here is you other csproj code -->

  <Target Name="_ResolveCopyLocalNuGetPackageXmls" AfterTargets="ResolveReferences">
    <ItemGroup>
      <ReferenceCopyLocalPaths Include="@(ReferenceCopyLocalPaths->'%(RootDir)%(Directory)%(Filename).xml')" Condition="'%(ReferenceCopyLocalPaths.NuGetPackageId)' != '' and Exists('%(RootDir)%(Directory)%(Filename).xml')" />
    </ItemGroup>
  </Target>
</Project>

PS这是来自https://github.com/ctaggart/SourceLink#known-issues（2.8.3版本）的修改代码

Answer 3

微软自己有关于这个问题的文档，我发现它非常有帮助。

简而言之，需要进行以下更改：

Startup.cs, ConfigureServices()

services.AddSwaggerGen(c =>
{
    ...
    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"));
});

{project_name}.csproj

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Answer 4

对于.Net Core 2和2.x版本，它稍有不同，对于那些使用较新版本的用户，您将创建您的 private void ConfigureSwagger(IServiceCollection services)构造函数，添加对swagger的引用，services.AddSwaggerGen(c => { c.SwaggerDoc(/*populate with your info */);然后定义一个新参数，该参数将成为您swagger XML文档的路径。 ： var filePath = Path.Combine(AppContext.BaseDirectory, "YourApiName.xml"); c.IncludeXmlComments(filePath);。

它看起来应该像这样：

private void ConfigureSwagger(IServiceCollection services)
    {
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new Info
            {
                Version = "v1",
                Title = "YourApiName",
                Description = "Your Api Description.",
                TermsOfService = "None",
                Contact = new Contact
                    {Name = "Contact Title", Email = "contactemailaddress@domain.com", Url = ""}
            });
            var filePath = Path.Combine(AppContext.BaseDirectory, "YourApiName.xml");
            c.IncludeXmlComments(filePath);
        });
    }

为此，您需要确保生成的输出已选中文档文件（请参见红色箭头），并且路径已正确设置。我注意到，您可以剥离预填充的路径并仅使用bin\YourApiName.xml，如下所示：

Answer 5

为您依赖的每个项目启用“ XML文档文件”复选框，以在构建时生成其文件。可以在项目的属性“构建”选项卡上完成。

要包括所有部署中的XML文件，请将此目标添加到已发布项目的csproj文件中：

<Target Name="PrepublishScript" BeforeTargets="PrepareForPublish">
    <ItemGroup>
        <DocFile Include="bin\*\*\*.xml" />
    </ItemGroup>
    <Copy SourceFiles="@(DocFile)" 
          DestinationFolder="$(PublishDir)" 
          SkipUnchangedFiles="false" />
</Target>

这会将所有XML文件从bin文件夹和嵌套的子文件夹（如bin\Release\netcoreapp1.1\）复制到publishdir。当然，您可以自定义该目标。