Mismatch between OpenAPI spec and enum deserialization

[ranma42]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

The OpenAPI spec documents takes into account the JSON serializer options for all parameters, but the server only applies them when parsing the body.

Expected Behavior

The OpenAPI spec should correctly represent the inputs for API endpoints, in path/query/header params (in addition to body params).
This is especially important when using tools that consume the OpenAPI spec (generating connectors, operating the endpoints with SwaggerUI & similar, ...).

Steps To Reproduce

This program reproduces the issue.

#:sdk Microsoft.NET.Sdk.Web
#:package Microsoft.AspNetCore.OpenApi@10.0.1

using System.Text.Json;
using System.Text.Json.Serialization;

var builder = WebApplication.CreateBuilder(args);
builder.Services.ConfigureHttpJsonOptions(opts =>
{
    opts.SerializerOptions.TypeInfoResolver = SerializerContext.Default;
    opts.SerializerOptions.Converters.Add(new JsonStringEnumConverter<TestEnum>(JsonNamingPolicy.KebabCaseLower));
});

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();
app.MapGet("/enum-value", (TestEnum test) => test).WithName("GetValue");
app.Run();

[JsonSerializable(typeof(TestEnum))]
internal partial class SerializerContext : JsonSerializerContext
{
}

enum TestEnum
{
    TheValue,
    MyValue,
    YourValue,
}

In the spec (available at http://localhost:5000/openapi/v1.json by runninng the program) the enum values are listed in kebab-case (the-value, my-value, your-value).

When the query param is passed in this form (for example http://localhost:5000/enum-value?test=my-value), the request is rejected (400 Bad Request).

Conversely, when TheValue is passed (http://localhost:5000/enum-value?test=TheValue), the result is the expected JSON ("the-value").

Note that the support for the camelCase naming policy will improve when #52497 is fixed, but snake/kebab-case won't be affected by that.

Exceptions (if any)

No response

.NET Version

10.0.101

Anything else?

.NET SDK:
 Version:           10.0.101
 Commit:            fad253f51b
 Workload version:  10.0.100-manifests.c57ac48b
 MSBuild version:   18.0.6+fad253f51

Runtime Environment:
 OS Name:     kali
 OS Version:  2025.4
 OS Platform: Linux
 RID:         linux-x64
 Base Path:   /usr/share/dotnet/sdk/10.0.101/

.NET workloads installed:
There are no installed workloads to display.
Configured to use workload sets when installing new manifests.
No workload sets are installed. Run "dotnet workload restore" to install a workload set.

Host:
  Version:      10.0.1
  Architecture: x64
  Commit:       fad253f51b

.NET SDKs installed:
  8.0.416 [/usr/share/dotnet/sdk]
  9.0.308 [/usr/share/dotnet/sdk]
  10.0.101 [/usr/share/dotnet/sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 8.0.22 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 9.0.11 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 10.0.1 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 8.0.22 [/usr/share/dotnet/shared/Microsoft.NETCore.App]
  Microsoft.NETCore.App 9.0.11 [/usr/share/dotnet/shared/Microsoft.NETCore.App]
  Microsoft.NETCore.App 10.0.1 [/usr/share/dotnet/shared/Microsoft.NETCore.App]

Other architectures found:
  None

Environment variables:
  Not set

global.json file:
  Not found

EDIT: linked the URL at which the app serves the OpenAPI spec

[rnagulapalle]

I took a quick look through the repo, and this does seem like a real cross-subsystem mismatch rather than just a docs bug.

What looks to be happening is:

• the OpenAPI side builds parameter schemas from JsonOptions.SerializerOptions, so enum converters/naming policies show up in the generated spec
• the minimal API binding side still treats query/header/route enums as string-to-enum parsing via ParameterBindingMethodCache -> Enum.TryParse(...)

So the two halves are currently making different promises:

• OpenAPI says my-value
• parameter binding still expects MyValue

A couple signals in the existing code/tests line up with that:

• OpenApiSchemaService is initialized from jsonOptions.Value.SerializerOptions
• GetOpenApiParameters_HandlesEnumParameterWithConverter already asserts converter-shaped enum values in parameter schemas
• ParameterBindingMethodCache uses Enum.TryParse for enums
• the request delegate tests only seem to cover enum-name inputs like ValueB, not converter-shaped names

That makes the repro here feel like a genuine behavior gap, not user error.

My read is that there are two plausible fixes, depending on which contract you want to preserve:

1. make non-body enum binding honor the configured enum string representation, or
2. stop projecting serializer enum naming policies into non-body OpenAPI parameter schemas until binding supports them

At minimum, this issue probably wants a regression test that pins the current mismatch across both layers, because right now the OpenAPI tests and the binding tests each pass independently while still disagreeing with each other.