Microsoft.AspNetCore.OpenApi: Enum type is missing when using JsonStringEnumConverter

[jeremia]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

We use Microsoft.AspNetCore.OpenApi v9.0.3

We have an endpoint for posting Leads:

public static void MapLeadsApiV1(this IEndpointRouteBuilder app)
{
    var leadsApi = app.MapGroup("/v1/leads").WithTags("Leads");

    leadsApi
        .MapPost(
            "/",
            (LeadV1 lead) => {...});
}

This is a simplified version of LeadV1:

public record LeadV1(
    LeadPurposeV1 Purpose,
);

public enum LeadPurposeV1
{
    GeneralSalesInquiry = 0,
    TestDriveRequest = 1,
}

We always want to expose enums as strings and therefore has the JsonStringEnumConverter registered globally:

builder.Services.Configure<JsonOptions>(options =>
{
    options.SerializerOptions.Converters.Add(new JsonStringEnumConverter());
});

The resulting schema for LeadPurposeV1 does not contain "type": "string" as would be expected:

"LeadPurposeV1": {
  "enum": [
    "GeneralSalesInquiry",
    "TestDriveRequest"
  ]
},

Note! It doesn't matter if the JsonStringEnumConverter is registered globally or just for the property in question.
Note 2: If we don't use JsonStringEnumConverter we get a schema looking like this:

"LeadPurposeV1": {
  "type": "integer"
},

That behaviour looks a lot like this bug which was supposedly fixed a long time ago:
#58195

Expected Behavior

"LeadPurposeV1": {
  "type": "string",
  "enum": [
    "GeneralSalesInquiry",
    "TestDriveRequest"
  ]
},

Steps To Reproduce

1. Create a REST api with a enum as part of the post body.
2. Reference Microsoft.AspNetCore.OpenApi v9.0.3
3. services.AddOpenApi()
4. app.MapOpenApi()
5. Run API and navigate to OpenApi spec

Exceptions (if any)

No response

.NET Version

9.0.201

Anything else?

.NET SDK:
Version: 9.0.201
Commit: 071aaccdc2
Workload version: 9.0.200-manifests.a3a1a094
MSBuild version: 17.13.13+1c2026462

Runtime Environment:
OS Name: Windows
OS Version: 10.0.26100
OS Platform: Windows
RID: win-x64
Base Path: C:\Program Files\dotnet\sdk\9.0.201\

.NET workloads installed:
[aspire]
Installation Source: VS 17.13.35828.75
Manifest Version: 8.2.2/8.0.100
Manifest Path: C:\Program Files\dotnet\sdk-manifests\8.0.100\microsoft.net.sdk.aspire\8.2.2\WorkloadManifest.json
Install Type: Msi

Configured to use loose manifests when installing new manifests.

Host:
Version: 9.0.3
Architecture: x64
Commit: 831d23e561

.NET SDKs installed:
9.0.104 [C:\Program Files\dotnet\sdk]
9.0.201 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
Microsoft.AspNetCore.App 6.0.25 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 6.0.36 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 8.0.14 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 9.0.3 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.NETCore.App 6.0.25 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 6.0.36 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 8.0.14 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 9.0.3 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.WindowsDesktop.App 8.0.14 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 9.0.3 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

Other architectures found:
x86 [C:\Program Files (x86)\dotnet]
registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]

Environment variables:
Not set

global.json file:
Not found

Learn more:
https://aka.ms/dotnet/info

Download .NET:
https://aka.ms/dotnet/download

[mhkolk]

I see a lot of @martincostello labeling work over many repos (saw it in Swashbuckle too) - are you asp.net contributor or MS associate and does your work actually mean the feature/bug was acknowledged by the team or is it just because you have extra time on hand?

I would appreciate asp.net team response on this because I noticed the same behaviour, actually even worse:

With the following code in place

builder.Services.Configure<JsonOptions>(options => { options.SerializerOptions.Converters.Add(new JsonStringEnumConverter()); });

I can confirm the output being as @jeremia posted, for example

"NullableOfTSMPValueTypeEnum": {
        "enum": [
          "Numeric",
          "Text",
          null
        ],
        "nullable": true
      },

1. Note the Nullable prefix there which I don't know how to get rid of, obviously enum as a standalone type within the spec is not nullable

2. Note the null value in there - what's going on with that?

3. Next, interestingly though if you have the following in place you will only get enums as integers

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

4. JsonStringEnumConverter messes up the order of enum string values in the resulting spec (issue that was already present in .NET 8)

Should be noted that this was enough for Swashbuckle to generate enums as string so having to do different set up now is somewhat weird - this could easily just be a bug. I do not know how and why the difference between SerializerOptions and JsonSerializerOptions came to be.

Suffice to say there will be no upgrading to Microsoft OpenAPI features from .NET 9 on our side any time soon bc this is way too half assed product..

[martincostello]

I see a lot of @martincostello labeling work over many repos (saw it in Swashbuckle too) - are you asp.net contributor or MS associate and does your work actually mean the feature/bug was acknowledged by the team or is it just because you have extra time on hand?

I'm a community triager in this repository, so I can label issues and pull requests to help route issues to the right team members, and can also chip-in on helping answer questions. Otherwise I'm just a member of the community who has contributed code to the repository over the years.

I'm the primary maintainer of Swashbuckle.AspNetCore, which is why you see me there.

Note the Nullable prefix there which I don't know how to get rid of, obviously enum as a standalone type within the spec is not nullable

You can use a transformer to customise things.

.AddControllers().AddJsonOptions()

This has no effect on how OpenAPI serialization works. The Minimal API options are used, not MVC's.

I do not know how and why the difference between SerializerOptions and JsonSerializerOptions came to be.

The former is MVC, the latter is Minimal APIs.

[mhkolk]

You can use a transformer to customise things.

I hope you're not saying we're supposed to do these basic things like proper understanding of nullable on our own?

.AddControllers().AddJsonOptions()

This has no effect on how OpenAPI serialization works. The Minimal API options are used, not MVC's.

I do not know how and why the difference between SerializerOptions and JsonSerializerOptions came to be.

The former is MVC, the latter is Minimal APIs.

I wish this was documented/mentioned more prominently somewhere. There will be a lot of .NET 9 upgrades from both MVC and Minimal APIs over the coming months. This means huge confusions for developers.

[ayuksekkaya]

Thank you for your help @martincostello . I am also facing this issue while trying to migrate from NSwag to Microsoft.AspNetCore.OpenApi Version="9.0.4". Interestingly enough, the enum conversion works fine if the enum is part of a response body but behaves like described above by @mhkolk and @jeremia when it's only part of the request body.

I also agree that we would appreciate it if something integral like this didn't have to go through a custom transformer.

[damianog]

Hi @ayuksekkaya, here my solution, at the moment I am using the 9.04 version of OpenApi
First of all I decorated my Enums with

[JsonConverter(typeof(JsonStringEnumConverter<WorkActivityState>))]
public enum WorkActivityState
{
    Idle = 0,
    Work = 1,
    Pause = 2,
    Close = 3
}

but then you need a transformer to fix the schema type

public class JsonStringEnumSchemaTransformer : IOpenApiSchemaTransformer
{
    public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)
    {
        if (context.JsonTypeInfo.Type.IsEnum)
        {
            var jsonStringEnumConverter = context.JsonTypeInfo.Type.GetCustomAttributes<JsonConverterAttribute>(false).FirstOrDefault()?.ConverterType;
            if (jsonStringEnumConverter is not null && jsonStringEnumConverter.IsGenericType && jsonStringEnumConverter.GetGenericTypeDefinition() == typeof(JsonStringEnumConverter<>)) 
            {
                schema.Type = "string";
            }
        }
        return Task.CompletedTask;
    }
}

and the service initialization

        builder.Services.AddOpenApi(options =>
        {
            options.AddSchemaTransformer<JsonStringEnumSchemaTransformer>();
        });

[mhkolk]

Well, this is just peachy.

[NWessel]

This works for me

internal class JsonStringEnumSchemaTransformer : IOpenApiSchemaTransformer
{
    public Task TransformAsync(
    OpenApiSchema schema,
    OpenApiSchemaTransformerContext context,
    CancellationToken cancellationToken)
    {
        var type = context.JsonTypeInfo.Type;
        if (type.IsEnum)
        {
            schema.Type = "string";

            schema.Enum.Clear();

            var names = Enum.GetNames(type);
            foreach (var name in names)
            {
                schema.Enum.Add(new OpenApiString(name));
            }
        }

        return Task.CompletedTask;
    }
}

[captainsafia]

Thanks for chiming in on this issue everyone!

This behavior occurs because our OpenAPI implementation uses the JSON schema generation support provided by System.Text.Json. That implementation optimizes for the JSON Schema spec which technically doesn't require you to set a type for enumerated values (see this ref).
Our OpenAPI implementation wraps the schema generation logic that STJ provides with our own defaults (like respecting [Description] attributes) and for other behaviors we provide schema transformers are an extensibility option.

So that's why you see the behavior you see here: STJ optimizes for emitting the strictest interpretation of the spec with minimal optional values. Some consumers of OpenAPI docs expect or require a type on the schema to guide in code generation or analysis. On the one hand, consumers of JSON schemas should be compliant with the rules defined in the spec. Technically, the schema generated here is correct and the additional type is an optional extra (which is why it isn't in the default set). On the other, this property feels fairly innocous to add.

I'd be happy to review a PR to to our transformation codepath (see here) to add types to enum schemas generated by STJ.

[MichaMican]

would love to see this implemented aswell!

[khellang]

We're also encountering OpenAPI tooling that thinks enums are objects (as opposed to strings) without the (optional) type attribute 😞