Simplifying Enum representation in C# Web APIs & Swagger

Enums — DotNet 7, EntityFramework Core 7, System.Text

Every software developer have faced this situation while working with web APIs where Enums is displayed as numbers following some patterns.

Here, It shows a schema that I have a model “UserEntity” with some properties such as Id, FirstName and UserRoles. Id and FirstName is straightforward int and a string but for UserRoles it accepts an array of numbers [0,1,2]. Wait! What? But I made beautiful models/DTOs with Enums for simple understanding. What will I be saying to Frontend developers ? Play with numbers and complicate your life with writing conversions ?

Lets Simplify our lifes :)

Technical Details: I will be using DotNet 7 with EntityFramework Core 7 along with InMemory Database.

I created a Web API project using our beloved JetBrains Rider IDE for DotNet. Created a basic UserEntity along with configuring DbContext. (No fancy stuff)

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

public enum UserRoles
{
    None,
    Admin,
    User
}        

With some basic logic to save this UserEntity and get back the saved UserEntity I get this response where our Enum UserRoles are represented by numbers.

Without going into much details why is this like this (Just Google how Enums are saved), we fix our life with one single Annotation using System.Text.Json.Serialization on our Enum Property 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; }
}        

Now If I use same Controller endpoint, I get a better readable UserRoles property

That was so easy ! World is a better place now right? I know. Welcome.

But the Swagger schema for my UserEntity still shows same number array as we saw in the start. Don’t worry another one liner 😆

Head to Program.cs and look for

builder.Services.AddControllers();        

and add this next to it. Simple !

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

Now you have a simple to read Enums in your Web APIs. Enjoy!

Pro Tip for Backend Developers : Just use Enum.Parse<T>() to parse strings from you APIs.

I would also like to share an interesting article related to Enums and APIs which I happen to checkout while dealing with this problem.

Video regarding the same can be found here: https://youtu.be/KlS-I72Q5-M?si=ajlD1UCpJtDDG5Hj

Recommendation : https://medium.com/codex/should-your-api-use-enums-340a6b51d6c3 by Ted Spence