五分钟带你学会.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

  • 13
    点赞
  • 6
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

笔神小卢

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值