五分钟带你学会.NetCore配置Swagger注释

在.NET 6项目中使用Swagger时，想要在Swagger UI中展示API方法和模型的注释。使用XML注释是实现这一点的好方法。以下是如何设置Swagger以使用XML注释的步骤： 

1.启用XML注释文件生成

点击项目文件（.csproj），编辑.csproj文件并添加以下代码：

  <!-- 设置为true以生成XML文档 -->
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <!-- 可选：如果你想要在生成的XML文件中包含具体的路径信息 -->
  <NoWarn>$(NoWarn);1591</NoWarn>

配置完成的效果图：

小提示：在.csproj文件中，<NoWarn>元素用于指定编译器应该忽略的警告代码列表。这些警告代码是用分号分隔的，你可以添加多个警告代码，编译器在编译时将不会显示这些警告。

1591是一个特定的警告代码，它表示“缺少对公共可见类型或成员的 XML 注释”。当你启用了XML文档文件的生成（通过设置<GenerateDocumentationFile>true</GenerateDocumentationFile>，编译器将会检查公共类型和成员是否有XML注释。如果发现没有XML注释，就会生成1591警告。

2.修改program.cs文件

配置swagger文档的信息，以及swagger的入口点。

var ApiName = "Web.Core";
builder.Services.AddSwaggerGen(c =>
{
    //配置swagger属性
    c.SwaggerDoc("V1", new OpenApiInfo
    {
        
        Version = "V1",
        Title = $"{ApiName} 接口文档——.NetCore 6.0",
        Description = $"{ApiName} HTTP API V1",
    });
    c.OrderActionsBy(o => o.RelativePath);


    // 设置XML文件路径
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    // 告诉Swagger使用这个XML文件
    c.IncludeXmlComments(xmlPath,true);
});



if (app.Environment.IsDevelopment())
{

    app.UseDeveloperExceptionPage();
}

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"Web.Core.API V1");

    //路径配置，设置为空，表示直接在根域名（localhost:port）访问该文件,注意localhost:port/swagger是访问不到的，如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "swagger";
    c.RoutePrefix = "swagger";
});

3 添加注释信息

4 启动项目 

启动项目访问swagger。url：https://localhost:port/swagger/index.html（注意替换自己的port）