目录

一、前言

二、.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，无需做其他配置。

如图：

----补充一种默认值设置方式2024-03-02

通过DefaultValue来指定默认值

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