Упрощение представления Enum в C# Web API и Swagger

Перечисления — DotNet 7, EntityFramework Core 7, System.Text

Каждый разработчик программного обеспечения сталкивался с этой ситуацией при работе с веб-API, где Enums отображается в виде чисел, следующих некоторым шаблонам.

Здесь показана схема, в которой у меня есть модель «UserEntity» с некоторыми свойствами, такими как Id, FirstNameи UserRoles. сильный>. Идентификатор и FirstName представляют собой просто intи строкуно для UserRoles он принимает массив чисел [0,1,2]. Ждать! Что? Но я сделал красивые модели/DTO с Enums для простоты понимания. Что я скажу разработчикам интерфейса ? Играть с числами и усложнять себе жизнь, записывая конверсии ?

Давайте упростим нашу жизнь :)

Технические подробности: я буду использовать DotNet 7 с EntityFramework Core 7вместе с базой данных InMemory.

Я создал проект веб-API, используя нашу любимую JetBrains Rider IDEдляDotNet. Создал базовый UserEntity вместе с настройкой DbContext. (Никаких причудливых вещей)

public class UserEntity
{
    public long Id { get; set; }
    public string? FirstName { get; set; }
    public UserRoles UserRoles { get; set; }
}

public enum UserRoles
{
    None,
    Admin,
    User
}

Используя некоторую базовую логику для сохранения этого UserEntity и возврата сохраненного UserEntity, я получаю этот ответ, где наши Enum UserRoles представлены числами.

Не вдаваясь в подробности, почему это так (просто погуглите, как сохраняются Enum), мы исправим нашу жизнь с помощью одной единственной Аннотации, используя System.Text.Json.Serialization на наше свойство Enum UserRoles.

[JsonConverter(typeof(JsonStringEnumConverter))]
public class UserEntity
{
    public long Id { get; set; }
    
    public string? FirstName { get; set; }

    [JsonConverter(typeof(JsonStringEnumConverter))]
    public UserRoles UserRoles { get; set; }
}

Теперь, если я использую ту же конечную точку контроллера, я получаю более удобочитаемое свойство UserRoles

Это было так просто! Мир стал лучше, верно? Я знаю. Добро пожаловать.

Но схема Swagger для моего UserEntity по-прежнему показывает тот же массив чисел, что и в начале. Не волнуйтесь, еще один лайнер 😆
Перейдите в Program.cs и найдите

builder.Services.AddControllers();

и добавьте это рядом с ним. Простой !

builder.Services.AddControllers().AddJsonOptions(options =>
 options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter()));

Теперь у вас есть простые для чтения Enums в ваших веб-API. Наслаждаться!

Совет для бэкенд-разработчиков: просто используйте Enum.Parse‹T›() для анализа строк из ваших API.

Я также хотел бы поделиться интересной статьей, связанной с Enums и API, которую мне довелось проверить, решая эту проблему.

Упрощение представления Enum в C# Web API и Swagger

Вопросы по теме