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.