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

目录

一、前言

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

二、 使用补充

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

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

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

一、前言

上篇文章介绍了在.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文档注释来修改这个默认值：

 修改后的效果：