.NET中的Swagger使用示例详解

2024-01-28 0 864 百度已收录

前言

现在很多项目都是前后端分离的项目,后端写好接口跟前端对接,需要后端提供接口文档、参数等注释,这上面花时间着这些东西,接口修改又要去修改文档,很不方便前后端人员开发

一、Swagger是什么?

Swagger (OpenAPI) 是一个与语言无关的规范,用于描述 REST API。

OpenAPI 与 Swagger关系
Swagger 项目已于 2015 年捐赠给 OpenAPI 计划,自此它被称为 OpenAPI,这两个名称可互换使用。 不过,“OpenAPI”指的是规范。
简而言之:
OpenAPI 是一种规范。
Swagger 是一种使用 OpenAPI 规范的工具。 例如,OpenAPIGenerator 和 SwaggerUI。

目前从NETCore从3.1起已经集成Sawwger,无需再去引用库,创建项目后运行API项目自动Sawwger接口文档的页面

介绍大家可能会关注的一些点

二、如何Swagger文档说明的信息

1.在AddSwaggerGen方法中写入文档信息

代码如下(示例):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
builder.Services.AddSwaggerGen(options =>
{
    //诸如作者、文档说明的信息
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "我的API",
        Description = "这是我的netcoreAPI项目",//描述信息
        Contact = new OpenApiContact
        {
            Name = "我是小小鱼",
            Url = new Uri("https://blog.csdn.net/qq_42335551")
        }
    });

2.运行效果

如图(示例):

二、文档UI界面标题、路由设置

如何修改标签页的名、和地址要怎么修改呢

1.在中间件UseSwaggerUI方法中配置

1
2
3
4
5
6
app.UseSwagger();
   app.UseSwaggerUI(c => {
       c.DocumentTitle = "后台接口列表";   //标签页标题
       c.SwaggerEndpoint("/swagger/v1/swagger.json", "公共模块");//接口文档json文件
       c.RoutePrefix =string.Empty;// 注:这里的路由修改后,launchSettings.json中的launchUrl对应需要调整为""
   });

在次启动项目 已经变成修改后的标签页和地址

三、文档UI界面添加接口注释

如何添加接口的注释呢

1.在 .csproj中配置

在解决方案资源管理器中右键单击该项目。
将 GenerateDocumentationFile 添加到 .csproj 文件中PropertyGroup节点下

1
<GenerateDocumentationFile>true</GenerateDocumentationFile>

2.在AddSwaggerGen方法中配置IncludeXmlComments

代码如下(示例):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
builder.Services.AddSwaggerGen(options =>
{
    //诸如作者、文档说明的信息
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "我的API",
        Description = "这是我的netcoreAPI项目",//描述信息
        Contact = new OpenApiContact
        {
            Name = "我是小小鱼",
            Url = new Uri("https://blog.csdn.net/qq_42335551")
        }
    });
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename), true);//true 显示控制器注释
});

运行效果,已经显示出我们的注释

可以在控制器、参数、实体类增加注释后,再次运行都有显示

四、对接口进行分组

1.在AddSwaggerGen、UseSwaggerUI分别添加如下信息

例如

1
2
options.SwaggerDoc("yw", new OpenApiInfo { Title = "业务模块", Version = "yw" });
options.SwaggerDoc("qt", new OpenApiInfo { Title = "其他模块", Version = "qt" });

例如

1
2
3
4
c.SwaggerEndpoint("/swagger/v1/swagger.json", "公共模块");//接口文档json文件
c.SwaggerEndpoint("/swagger/yw/swagger.json", "业务模块");
c.SwaggerEndpoint("/swagger/qt/swagger.json", "其他模块");
c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.List);//接口不展开None

 2.在controller或者action上打上ApiExplorerSettings特性

例如[ApiExplorerSettings(GroupName = “v1”)]

总结

有Sawwger有利于前后端开发人员接口的对接,调试,功能上挺丰富的,简单的写了以上几点。

收藏 (0) 打赏

感谢您的支持,我会继续努力的!

打开支付宝扫一扫,即可进行扫码打赏哦,您的支持,是我继续创作的动力。
点赞 (0)

中和威客保留所有权利,未经本站书面许可不得转载本站内容!文中观点不代表本站立场!

中和威客 C# .NET中的Swagger使用示例详解 https://www.izhwk.com/archives/109

常见问题
  • 您需要注册成为本站会员,然后再通过会员中心的升级VIP功能,方可成为本站的VIP会员。
查看详情
  • 首先您需要注册成为本站会员,然后到会员中心充值,充值后支付对应资源的查看金额即可查看付费内容。
查看详情

相关文章

猜你喜欢
评论
暂无评论
.NET中的Swagger使用示例详解-海报

分享本文封面