Question

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

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

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

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

Answer 1

启用＆＃34; XML文档文件＆＃34;您依赖的每个项目的复选框在构建时生成文件。它可以在项目的属性Build选项卡中完成。

要在部署时包含所有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 2

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

在.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文档文件”选项并保存。

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>

P.S。这是https://github.com/ctaggart/SourceLink#known-issues（2.8.3版）中的修改代码

Answer 5

Microsoft documentation here建议在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 6

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

19    21    23
20    22    24

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

6 个答案: