.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文檔注釋來修改這個預設值：

 修改後的效果：