enum get represented as int in openapi generation

[nielsq]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Hey everyone,
enums will are represented as integer? Should there not being a enum also in the json for that?

I have a class, called Node with an enum called Rank

Here is the generated json where it´s just an integer.

I also saw this issue when people use swagger, but not a solution on how to fix it here.
Any solutions?

Thanks!

Expected Behavior

No response

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

No response

Anything else?

No response

[MihuBot]

I'm a bot. Here is a possible related and/or duplicate issue (I may be wrong):

• OpenApi Enums generating no schema #58230

[martincostello]

What is the configuration of your JSON serialization options for Minimal APIs?

If JsonStringEnumConverter isn't being used, for instance, then enums will be represented as integers by default, so the OpenAPI document will reflect that.

[gehongyan]

This issue does exist.

If a developer configures JsonStringEnumConverter, then representing enums as strings in the OpenAPI document and listing all possible string values is reasonable.

However, if this JSON converter is not configured and enum values are serialized as their underlying integer values, the OpenAPI document should still list the defined enum values in their integer form.

---

For example, define an enum type:

public enum ResponseCode
{
    Success = 0,
    Error = 1
}

If we specify the JSON converter:

[JsonConverter(typeof(JsonStringEnumConverter))]

The OpenAPI schema for ResponseCode at #/components/schemas/ResponseCode will be:

{
  "enum": [
    "Success",
    "Error"
  ]
}

Seems good!

However, if we remove the JsonStringEnumConverter, the schema will be:

{
  "type": "integer"
}

The schema indicates only that the result is an integer, but it does not list all defined enum values (as integers) under the enum field.

What we want is:

{
  "enum": [
    0,
    1
  ],
  "type": "integer"
}

At present, I have to add such a schema transformer to achieve it:

/// <summary>
///     Transforms enum types in the OpenAPI schema to include their defined integer values in the enum array,
///     allowing them to be represented as integers in the generated OpenAPI document.
/// </summary>
internal class OpenApiEnumSchemaTransformer : IOpenApiSchemaTransformer
{
    /// <inheritdoc />
    public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context,
        CancellationToken cancellationToken)
    {
        Type type = Nullable.GetUnderlyingType(context.JsonTypeInfo.Type) ?? context.JsonTypeInfo.Type;
        if (!type.IsEnum)
            return Task.CompletedTask;

        schema.Enum = Enum
            .GetValues(type)
            .OfType<IConvertible>()
            .Select(JsonNode (value) => JsonValue.Create(value.ToInt32(null)))
            .ToList();

        // // AnyOf is another option to represent enum values as integers,
        // // which allows for more detailed descriptions for each enum member.
        // schema.AnyOf = Enum
        //     .GetValues(type)
        //     .OfType<IConvertible>()
        //     .Select(value => new OpenApiSchema
        //     {
        //         Type = JsonSchemaType.Integer,
        //         Enum = [JsonValue.Create(value.ToInt32(null))],
        //         // The description should be parsed in some order, for example:
        //         // - XML documentation summary of the enum member
        //         // - JsonStringEnumMemberName attribute of the enum member
        //         // - Description attribute of the enum member
        //         // - Fallback to the enum member name and value if no description is found
        //         Description = $"{Enum.GetName(type, value)} = {value.ToInt32(null)}"
        //     })
        //     .ToList<IOpenApiSchema>();

        return Task.CompletedTask;
    }
}