.Net5下使用OpenAPI(Swagger)生成webapi文档补充

2023-12-12 01:48

本文主要是介绍.Net5下使用OpenAPI(Swagger)生成webapi文档补充,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

目录

一、前言

二、.net5下使用Swagger接口文档

二、 使用补充

1.接口返回结果日期时间类型格式化

2.设置接口返回结果中字段大小写原样返回

3.修改Swagger文档中Example Value示例参数的默认值

4.修改Swagger文档的浏览器tab标签的标题

5.设置方法按控制器折叠


一、前言

上篇文章介绍了在.netcore2.1下使用Swagger文档的方法。

二、.net5下使用Swagger接口文档

项目升级到.net5以后配置基本没有变化,只是不再需要专门手动添加Swashbuckle.AspNetCore Nuget包的引用

 .net5下创建ASP.NET Core WebAPI项目时默认勾选了“启用OpenAPI支持”,OpenAPI也就是Swagger,项目创建完成我们可以看到自动添加了对Swashbuckle.AspNetCore包的引用

二、 使用补充

1.接口返回结果日期时间类型格式化

如果不做处理Datetime类型字段在接口返回后使用的是UTC时间,类似2021-09-18T06:26:42.119Z格式的

统一使接口返回yyyy-MM-dd HH:mm:ss时间

public void ConfigureServices(IServiceCollection services){services.AddControllers().AddNewtonsoftJson(options =>{//设置接口返回时间格式options.SerializerSettings.DateFormatString = "yyyy-MM-dd HH:mm:ss";});}

2.设置接口返回结果中字段大小写原样返回

Swagger文档示例和API接口默认会把实体类中的字段首字母转换为小写返回,如果想保持原样可以使用如下配置:

public void ConfigureServices(IServiceCollection services){services.AddControllers().AddNewtonsoftJson(options =>{//设置接口返回时间格式//options.SerializerSettings.DateFormatString = "yyyy-MM-dd HH:mm:ss";options.SerializerSettings.ContractResolver = new Newtonsoft.Json.Serialization.DefaultContractResolver();//json字符串大小写原样输出}).AddJsonOptions(config =>{config.JsonSerializerOptions.PropertyNamingPolicy = null;//解决swagger文档示例字段首字母被转换为小写的问题});}

 可以看到Example Value示例和Try it out中接口实际返回结果都已经变成了和实体中保存一致的首字母大写了

3.修改Swagger文档中Example Value示例参数的默认值

如上图的查询接口入参分页每页条数和当前页码都是int类型,示例文档自动生成的默认值为0(即int的默认值),做为示例值,这里使用0是十分不合理的,前后端分离开发时容易误导前端同事,而且我们使用Try it out实际测试接口时每次都需要手动去修改这个值,十分的不方便。

可以在入参实体字段上使用example文档注释来修改这个默认值:

 修改后的效果:

如果是DateTime类型的参数,使用<example>2022-05-02</example>标记指定示例参数默认格式时会自动转换为如下格式

2022-05-02T00:00:00.0000000

但是这种时间格式并不是我们想要的,比如我们只想要指定yyyy-MM-dd或者yyyy-MM-dd HH:mm:ss,添加nuget包引用即可:Swashbuckle.AspNetCore.Annotations,无需做其他配置。

如图:

4.修改Swagger文档的浏览器tab标签的标题

 默认的Swagger文档标题是Swagger UI,如果打开多个项目时无法从标题上区分开来。

在Configure方法中使用如下方法指定浏览器title即可

效果图:

 

5.设置方法按控制器折叠

控制器中方法过多时查找一个方法需要向下滚动好久才找到对应的控制器,实际开发中带来了很多不便,我们可以设置Swagger文档根据控制器进行折叠:

                app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "swagger v1");c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None);});

这篇关于.Net5下使用OpenAPI(Swagger)生成webapi文档补充的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/482821

相关文章

深入理解Go语言中二维切片的使用

《深入理解Go语言中二维切片的使用》本文深入讲解了Go语言中二维切片的概念与应用,用于表示矩阵、表格等二维数据结构,文中通过示例代码介绍的非常详细,需要的朋友们下面随着小编来一起学习学习吧... 目录引言二维切片的基本概念定义创建二维切片二维切片的操作访问元素修改元素遍历二维切片二维切片的动态调整追加行动态

prometheus如何使用pushgateway监控网路丢包

《prometheus如何使用pushgateway监控网路丢包》:本文主要介绍prometheus如何使用pushgateway监控网路丢包问题,具有很好的参考价值,希望对大家有所帮助,如有错误... 目录监控网路丢包脚本数据图表总结监控网路丢包脚本[root@gtcq-gt-monitor-prome

Python通用唯一标识符模块uuid使用案例详解

《Python通用唯一标识符模块uuid使用案例详解》Pythonuuid模块用于生成128位全局唯一标识符,支持UUID1-5版本,适用于分布式系统、数据库主键等场景,需注意隐私、碰撞概率及存储优... 目录简介核心功能1. UUID版本2. UUID属性3. 命名空间使用场景1. 生成唯一标识符2. 数

SpringBoot中如何使用Assert进行断言校验

《SpringBoot中如何使用Assert进行断言校验》Java提供了内置的assert机制,而Spring框架也提供了更强大的Assert工具类来帮助开发者进行参数校验和状态检查,下... 目录前言一、Java 原生assert简介1.1 使用方式1.2 示例代码1.3 优缺点分析二、Spring Fr

Android kotlin中 Channel 和 Flow 的区别和选择使用场景分析

《Androidkotlin中Channel和Flow的区别和选择使用场景分析》Kotlin协程中,Flow是冷数据流,按需触发,适合响应式数据处理;Channel是热数据流,持续发送,支持... 目录一、基本概念界定FlowChannel二、核心特性对比数据生产触发条件生产与消费的关系背压处理机制生命周期

java使用protobuf-maven-plugin的插件编译proto文件详解

《java使用protobuf-maven-plugin的插件编译proto文件详解》:本文主要介绍java使用protobuf-maven-plugin的插件编译proto文件,具有很好的参考价... 目录protobuf文件作为数据传输和存储的协议主要介绍在Java使用maven编译proto文件的插件

SpringBoot线程池配置使用示例详解

《SpringBoot线程池配置使用示例详解》SpringBoot集成@Async注解,支持线程池参数配置(核心数、队列容量、拒绝策略等)及生命周期管理,结合监控与任务装饰器,提升异步处理效率与系统... 目录一、核心特性二、添加依赖三、参数详解四、配置线程池五、应用实践代码说明拒绝策略(Rejected

C++ Log4cpp跨平台日志库的使用小结

《C++Log4cpp跨平台日志库的使用小结》Log4cpp是c++类库,本文详细介绍了C++日志库log4cpp的使用方法,及设置日志输出格式和优先级,具有一定的参考价值,感兴趣的可以了解一下... 目录一、介绍1. log4cpp的日志方式2.设置日志输出的格式3. 设置日志的输出优先级二、Window

Ubuntu如何分配​​未使用的空间

《Ubuntu如何分配​​未使用的空间》Ubuntu磁盘空间不足,实际未分配空间8.2G因LVM卷组名称格式差异(双破折号误写)导致无法扩展,确认正确卷组名后,使用lvextend和resize2fs... 目录1:原因2:操作3:报错5:解决问题:确认卷组名称​6:再次操作7:验证扩展是否成功8:问题已解

Qt使用QSqlDatabase连接MySQL实现增删改查功能

《Qt使用QSqlDatabase连接MySQL实现增删改查功能》这篇文章主要为大家详细介绍了Qt如何使用QSqlDatabase连接MySQL实现增删改查功能,文中的示例代码讲解详细,感兴趣的小伙伴... 目录一、创建数据表二、连接mysql数据库三、封装成一个完整的轻量级 ORM 风格类3.1 表结构