Como retornar uma string de um enum em uma API .NET

Introdução

Por padrão API's .NET retornam o valor inteiro(int) de um enum mas nem sempre esse é o cenário ideal de retorno, para algumas situações desejamos retornar a string do enumerador, o .NET oferece a opção de serializar valores enum como strings.

Neste artigo vou criar um exemplo de API que retorna a string de um enum.
Você pode acessar o repositorio desse projeto em exemplo-dotnet-enum.

Pré-requisitos

• .NET 6.0
• Visual Studio Code (VS Code)
• Terminal de sua preferência

Criando o projeto

Com o comando dotnet new webapi vamos criar um projeto webapi, o parâmetro -o indica o caminho onde o projeto será criado.

dotnet new webapi -o exemplo-dotnet-enum

Para esse exemplo não vamos precisar dos arquivos WeatherForecast.cs e WeatherForecastController.cs os mesmos podem ser deletados.

Vamos criar três novos arquivos, StatusClienteEnum.cs, Cliente.cs e ClienteController.cs Os mesmos serão criados em pastas separadas para uma mínima organização.

Enums/StatusClienteEnum.cs

Models/Cliente.cs

Controllers/ClienteController.cs

Feito isso podemos executar nossa api observe em qual porta está rodando e acesse o swagger, no exemplo estou acessando o seguinte endereço https://localhost:7151/swagger/index.html

Executando a rota Get/Cliente a API retorna os clientes, mas ainda não temos o resultado esperado pois está sendo retornado o inteiro dos enums.

Para o .NET 6 precisamos mudar a classe Program.cs adicionando a extensão AddJsonOptions() em builder.Services.AddControllers() Essa extensão vai nos permitir configurar as opções do serializador JSON usadas pelos controllers.
(se você estiver utilizando o .NET 5 as mudanças devem ser feitas no arquivo Startup.cs)

A classe JsonStringEnumConverter precisa da referência using System.Text.Json.Serialization. No final o Program.cs ficará assim:

Vamos executar novamente nossa api e teremos o seguinte resultado:

Conclusão

O método AddJsonOptions nos permite configurar as opções para serialização JSON, e por padrão os enums são serializados como números (int), para serializar os enums como texto (string) utilizamos uma instância da classe JsonStringEnumConverter como parâmetro do método JsonSerializerOptions.Converters.Add() realizando assim a conversão de enums para seus respectivos textos. Para mais informações sobre JsonSerializerOptions consulte a documentação oficial - Microsoft docs.