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

ix0qys7i  于 2023-10-21  发布在  .NET
关注(0)|答案(8)|浏览(130)

我需要斯瓦格生成API文档,包括用户界面测试操作。
在我的项目中使用ASP.NET时,生成了deps XML文件,一切正常,看起来像这样:

但是当我在我的项目中使用ASP.NETCore时,没有生成depsXML文件。它只是生成我的项目注解XML文件,看起来像这样:

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

goqiplq2

goqiplq21#

对于**.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,就像下面这样:

更新:如果这些更改没有按预期工作,请检查配置。在本例中,配置设置为“0”。如果你是从一个不同的环境(env)运行,你可能需要检查这些设置是否适用于该env。
更新2:自从OpenAPI发布以来,我想我应该更新我的示例(下面),以更准确地引用this specification,它应该遵循类似的内容:

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")
                        }
                    });
            });
jecbmhm3

jecbmhm32#

为您所依赖的每个项目启用“XML文档文件”复选框,以便在构建时生成其文件。它可以在项目的属性Build选项卡中完成。
要在部署时包含所有XML文件,请将此目标添加到已发布项目的csproj文件中:

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

这将从bin文件夹和嵌套目录(如bin\Release\netcoreapp1.1\)复制所有XML文件到publish目录。当然,你可以定制这个目标。

lskq00tm

lskq00tm3#

我用这种方法注册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);
                    }
                }
ux6nzvsh

ux6nzvsh4#

对于.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版本)

uqzxnwby

uqzxnwby5#

微软自己有这个问题的文档,我发现它很有帮助。
简而言之,需要作出以下改变:
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>
wrrgggsh

wrrgggsh6#

Microsoft documentation here建议在csproj文件中使用DocumentationFile标记。
只需确保您的部署具有正确的构建(Release/Release):

<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>
h7appiyu

h7appiyu7#

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

0kjbasz6

0kjbasz68#

对于.Net 7,在项目文件中添加:

<PropertyGroup>
    ...
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

在Program.cs文件中,添加:

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

相关问题