AddOpenApi not respect JsonSerializerOptions Configurations

[mu-dawood]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I'm configuring my json options using

builder.Services.AddControllers().AddJsonOptions(x =>
            {
                x.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
                x.JsonSerializerOptions.PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.SnakeCaseLower;
            })
/// add open api
builder.Services.AddOpenApi();

But the generated schema neither respect JsonStringEnumConverter nor SnakeCaseLower

Expected Behavior

No response

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

No response

Anything else?

No response

[martincostello]

This isn't a bug - OpenAPI uses the serialization options associated with HTTP/Minimal APIs, not MVC's.

You need to configure the same serialization customisations for OpenAPI by using the ConfigureHttpOptions method.

[vitasystems]

The usage of this feature is in the best case scenario very confusing and counter intuitive.

In my opinion this is a bug because the behavior that one would expect intuitively is that the AddOpenApi would actually document my controller actions. ConfigureHttpJsonOptions does not work for Controller API only for Minimal API.

Also in my opinion this issue is not resolved. It is also not documented. At best configuring json options twice is a "workaround".

[mu-dawood]

I agree with @vitasystems its a bug
nothing in the documentations said that it works only for minimal Api

The "workaround" fixed my issue but i think it must be fixed or even update the docs

[martincostello]

I suggest creating a new issue in the AspNetCore docs repo to get a clarification added.

I doubt it will be "fixed" as it is working as designed. Otherwise to support MVC it would need to depend on it, meaning pulling significantly more code into apps wanting to use it with Minimal APIs.

[vitasystems]

I suggest creating a new issue in the AspNetCore docs repo to get a clarification added.

I doubt it will be "fixed" as it is working as designed. Otherwise to support MVC it would need to depend on it, meaning pulling significantly more code into apps wanting to use it with Minimal APIs.

You say it is working as designed.... But it is not working for anyone using Controllers API. So it is designed to not work with Controllers API?

What is going to happen when the issue is not just about the Json Options? Does this mean that development of this feature it is solely based on the Minimal API and any one using Controller API should not throw away their investment with this "feature" and just stick to the deprecated (soft deprecated) Swashbuckle?

I mean what are the options here? Microsoft has removed swashbuckle from the templates and suppossedly added OpenAPI support in replacement.

[martincostello]

@captainsafia Would you like to chime in here?

[Rick-Anderson]

@captainsafia Would you like to chime in here?

@captainsafia after you comment I'll update the doc See dotnet/AspNetCore.Docs#34602

[steveo068]

I was able to make OpenAPI work with a controller and an enum serialized as string.

On the enum, you need to add the [JsonConverter(typeof(JsonStringEnumConverter))] attribute on the enum, and it is compatible with [JsonStringEnumMemberName]. The caviat is that you also need to make sure that the controller has the [ApiController] attribute, just inheriting from Controller or ControllerBase is not enough.

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum MyEnum
{
    [JsonStringEnumMemberName("FirstValue")]
    FirstValue,
    [JsonStringEnumMemberName("second-value")]
    SecondValue,
}

Produced OpenAPI model contains:

      "MyEnum": {
        "enum": [
          "FirstValue",
          "second-value"
        ]
      },

See this ticket #58938 for the [ApiController] attribute.
I also opened a ticket for documentation update dotnet/AspNetCore.Docs#34641.

[vitasystems]

I was able to make OpenAPI work with a controller and an enum serialized as string.

On the enum, you need to add the [JsonConverter(typeof(JsonStringEnumConverter))] attribute on the enum, and it is compatible with [JsonStringEnumMemberName]. The caviat is that you also need to make sure that the controller has the [ApiController] attribute, just inheriting from Controller or ControllerBase is not enough.

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum MyEnum
{
[JsonStringEnumMemberName("FirstValue")]
FirstValue,
[JsonStringEnumMemberName("second-value")]
SecondValue,
}
Produced OpenAPI model contains:

  "MyEnum": {
    "enum": [
      "FirstValue",
      "second-value"
    ]
  },

See this ticket #58938 for the [ApiController] attribute. I also opened a ticket for documentation update dotnet/AspNetCore.Docs#34641.

This issue is not just the JsonStringEnumConverter...

The fact is that it does not respect the json options for Controller API unless you set the same exact options also for Minimal API even if you are NOT using Minimal API.

In my case for example I had other settings like casing and default value handling etc none of these are respected.

The OpenApi feature only takes into account Minimal API json options.

And then you end up with something like this(two of everything) when using Controller API:

`mvc.AddJsonOptions(options =>
{
if(settings != null)
{
var jsonOptions = options.JsonSerializerOptions;

    jsonOptions.DefaultIgnoreCondition = settings.DefaultIgnoreCondition;
    jsonOptions.WriteIndented = settings.WriteIndented;
    jsonOptions.UnmappedMemberHandling = settings.UnmappedMemberHandling;
    jsonOptions.UnknownTypeHandling = settings.UnknownTypeHandling;
    jsonOptions.PropertyNamingPolicy = settings.PropertyNamingPolicy;
    jsonOptions.PropertyNameCaseInsensitive = settings.PropertyNameCaseInsensitive;
    jsonOptions.MaxDepth = settings.MaxDepth;
}

});

services.ConfigureHttpJsonOptions(options =>
{
if(settings != null)
{
var jsonOptions = options.SerializerOptions;

    jsonOptions.DefaultIgnoreCondition = settings.DefaultIgnoreCondition;
    jsonOptions.WriteIndented = settings.WriteIndented;
    jsonOptions.UnmappedMemberHandling = settings.UnmappedMemberHandling;
    jsonOptions.UnknownTypeHandling = settings.UnknownTypeHandling;
    jsonOptions.PropertyNamingPolicy = settings.PropertyNamingPolicy;
    jsonOptions.PropertyNameCaseInsensitive = settings.PropertyNameCaseInsensitive;
    jsonOptions.MaxDepth = settings.MaxDepth;
}

});`

And imho this looks like a hacky workaround at best.

[captainsafia]

Sorry for the delay in responding here.

I've chimed in on this topic in a couple of different GitHub threads so it probably merits a prominent note in the docs.

Some clarifications:

1. The OpenAPI feature is designed to work with MVC.
2. The specific gap here is that OpenAPI (and pretty much every other non-MVC component that interacts with the JsonSerializer) uses the JsonOptions type that is defined in the Microsoft.AspNetCore.Http namespace and assemblies.
3. Because of the above, if you're using non-default serializer options you need to configure them using both the HTTP and MVC types.

This problem has existed since .NET 7 but is more in-your-face now with the reliance on JsonOptions for all schema generation. This might be the the right time to include an analyzer/codefix pattern in the framework to warn about this.

Alternatively, now that we have a mechanism for shipping Roslyn assets in the OpenAPI package we can slot it in there too.

[vitasystems]

Sorry for the delay in responding here.

I've chimed in on this topic in a couple of different GitHub threads so it probably merits a prominent note in the docs.

Some clarifications:

1. The OpenAPI feature is designed to work with MVC.
2. The specific gap here is that OpenAPI (and pretty much every other non-MVC component that interacts with the JsonSerializer) uses the JsonOptions type that is defined in the Microsoft.AspNetCore.Http namespace and assemblies.
3. Because of the above, if you're using non-default serializer options you need to configure them using both the HTTP and MVC types.

This problem has existed since .NET 7 but is more in-your-face now with the reliance on JsonOptions for all schema generation. This might be the the right time to include an analyzer/codefix pattern in the framework to warn about this.

Alternatively, now that we have a mechanism for shipping Roslyn assets in the OpenAPI package we can slot it in there too.

This still sounds like a "work around". It is clear that when you use Controller API you dont use the same json options as when you use Minimal API. And this seems to me like a big enough delta to drop this feature on all the teams I lead.

I will be moving back to Swagger and not waste any more money or time on this "feature".