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

Question

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

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

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

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

Answer 1

对于 .Net Core 2 到 3.1 版本略有不同，对于那些使用较新版本的人来说，您可以创建自己的

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 = "[email protected]", Url = ""}
            });
            var filePath = Path.Combine(AppContext.BaseDirectory, "YourApiName.xml");
            c.IncludeXmlComments(filePath);
        });
    }

为此，您需要确保构建的输出已检查文档文件（请参见红色箭头）并正确设置路径。我注意到你可以去掉预填充的路径并只使用

bin\YourApiName.xml

，就像下面这样：

更新：如果这些更改未按预期工作，请检查配置。在示例中，配置设置为“调试”。如果您从不同的环境 (env) 运行，您可能需要检查这些设置是否适用于该环境。

更新 2：自从 OpenAPI 发布以来，我想我应该更新我的示例（如下）以显示对 此规范 的更准确参考，它应该遵循类似以下内容：

services.AddSwaggerGen(o =>
            {
                o.SwaggerDoc("v1",
                    new OpenApiInfo
                    {
                        Title = "Your API Name",
                        Description = "Your API Description",
                        Version = "v1",
                        TermsOfService = null, 
                        Contact = new OpenApiContact 
                        {
                            // Check for optional parameters
                        },
                        License = new OpenApiLicense 
                        {
                            // Optional Example
                            // Name = "Proprietary",
                            // Url = new Uri("https://someURLToLicenseInfo.com")
                        }
                    });
            });

Answer 2

为您依赖的每个项目启用“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\

）复制到 

publish

 目录。当然，您可以自定义该目标。

Answer 3

我用这种方式来注册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 4

对于 .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>

附注这是修改后的代码

https://github.com/ctaggart/SourceLink#known-issues（2.8.3 版本）

Answer 5

微软自己有关于这个问题的文档

这里，我发现它非常有帮助。

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

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 6

Microsoft

文档建议在您的 csproj 文件中使用 DocumentationFile

 标签。

只需确保您的部署具有正确的版本（发布/调试）：

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>bin\Release\netcoreapp2.0\APIProject.xml</DocumentationFile>
</PropertyGroup>

我刚刚在实践中使用了它（进行了下面的调整）并且效果很好：

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
  <DocumentationFile>bin\Release\$(TargetFramework)\$(MSBuildProjectName).xml</DocumentationFile>
  <NoWarn>1701;1702;1705;1591</NoWarn>
</PropertyGroup>

Answer 7

在.net core 3.1中，请按照以下步骤操作：

转到 Startup.cs 页面并添加以下代码

public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<ApplicationDbContext>(options =>
                options.UseSqlServer(
                    Configuration.GetConnectionString("DefaultConnection")));
            services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
                .AddEntityFrameworkStores<ApplicationDbContext>();
            services.AddSwaggerGen(c => { 
                c.SwaggerDoc("v1", new OpenApiInfo 
                {
                    Title="Book Store API",
                    Version="v1",
                    Description="This is an educational site"
                });
                var xfile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xpath = Path.Combine(AppContext.BaseDirectory,xfile);
                c.IncludeXmlComments(xpath);
            });
            
            services.AddControllers();
        }

之后，转到项目的“属性”，然后单击“XML 文档文件”选项并保存。