ASP.NET Core 6 在 Swagger UI 中顯示 列舉的名稱而不是數字

在 API 參數中使用列舉可以避免我們需要記憶相對比較沒有意義的數字，例如下面的 Controller 就是使用 IceLevel 列舉作為參數傳遞冰塊的分量：

    
[ApiController]
[Route("[controller]")]
public class RuyutController : ControllerBase
{
    public enum IceLevel
    {
        None, // 去冰
        Little, // 微冰
        Less, // 少冰
        Normal, // 正常冰
        More, // 多冰
    }

    [HttpGet]
    public IActionResult Get(IceLevel iceLevel)
    {
        return Ok(iceLevel);
    }
}
    

但是可以發現在 Swashbuckle.AspNetCore 6.2.3 所產生的 Swagger UI 中參數是以數字的方式出現

實際測試呼叫所提供的選單也是同樣的是數字，而不是我們想要的使用列舉的名稱

一開始以為是不支援使用列舉的名稱傳遞，但實際測試後發現可以成功接收

    
https://localhost:7185/Ruyut?iceLevel=More
    

解決方式為在 Program.cs 中加入下面的程式碼：

  

builder.Services.Configure<Microsoft.AspNetCore.Http.Json.JsonOptions>(options =>
{
    options.SerializerOptions.Converters.Add(new System.Text.Json.Serialization.JsonStringEnumConverter());
});
builder.Services.Configure<Microsoft.AspNetCore.Mvc.JsonOptions>(options =>
{
    options.JsonSerializerOptions.Converters.Add(new System.Text.Json.Serialization.JsonStringEnumConverter());
});

註：筆者在測試時對 Web API 專案有效的是 Microsoft.AspNetCore.Mvc.JsonOptions ，而對 MVC 專案有效的是 Microsoft.AspNetCore.Mvc.JsonOptions，筆者並未進行深入的測試，暫時將兩者皆放上，若有更好的建議歡迎補充

重新啟動後就會發現出現列舉的名稱

測試時也能夠正常呼叫