How to show enum names instead of numbers in Swagger API docs?

Other Questions API
1

I’m working on a REST API and I want Swagger documentation to show enum names like “Basic”, “Standard”, “Premium” instead of numeric values 0, 1, 2.

The goal is to make it easier for developers to use the API without checking enum definitions every time they make requests.

I attempted using DescribeAllEnumsAsStrings but this caused issues because the server started expecting string inputs instead of enum types, which broke model validation.

Here’s my current setup:

public class Message 
{
    [Required]
    public string Text {get; set;}

    [Required]
    [EnumDataType(typeof(Level))]
    public Level Level {get; set;}
}

public class MessagesController : ApiController
{
    [HttpPost]
    public IHttpActionResult CreateMessage(Message message)
    {
        // Model validation fails when using DescribeEnumsAsStrings
        if (!ModelState.IsValid)
            return BadRequest("Invalid data")

        // Process message
    }

    // Want to display "Basic", "Standard", "Premium" in docs instead of 0, 1, 2
    [HttpGet]
    public IHttpActionResult GetByLevel(Level level)
    {
        // Filter logic here
    }
}

public enum Level
{
    Basic, 
    Standard,
    Premium
}

Is there a way to display string names in Swagger while keeping enum type validation on the server side?

2

Had this exact problem last year. Fixed it by setting up the JSON serializer globally in WebApiConfig instead of using converter attributes. Just add config.Formatters.JsonFormatter.SerializerSettings.Converters.Add(new StringEnumConverter()); in your Register method. This way all your enum properties serialize as strings across the entire API. Swagger picks up the string representation automatically and you keep proper enum validation on the server side. Unlike DescribeAllEnumsAsStrings, this actually changes how enums get serialized, not just the docs, so validation still works.

3

You can fix this in SwaggerConfig.cs without touching your model. Add a custom schema filter that converts enum values to strings just for documentation. Create a class implementing ISchemaFilter and override the Apply method - check for enum types, then swap the numeric values with string names in the schema. Your API contract stays the same, but Swagger UI shows readable enum names instead of numbers. The server still handles numeric enum values normally, developers just see descriptive names in the docs. This avoids the validation problems you hit with DescribeAllEnumsAsStrings since it only changes the documentation layer.

4

try using the JsonConverter attribute for your enum. Just add [JsonConverter(typeof(StringEnumConverter))] on the Level property in your Message class. This way, swagger will show names like Basic, Standard, Premium and still keep enum validation intact. worked for me!