Microsoft.AspNetCore.OpenApi Handling Of Mvc Json Options

[RyanThomas73]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

Related issue: #57891

Problem:
For an AspNetCore.Mvc api, the request and response json serializer settings are configured using an options specific to the AspNetCore.Mvc packages.

In the Microsoft.AspNetCore.OpenApi packages, the open api document services rely solely on the Microsoft.AspNetCore.Http.Json.JsonOptions value to control json serializer settings. As mentioned in the related issue, this was done to avoid the need to reference the .Mvc packages from the OpenApi packages.

However, requiring consumers to always change their Microsoft.AspNetCore.Http.Json.JsonOptions to match their Mvc ones in order for the open api spec doc generation to work is not viable in many situations. Changing the Microsoft.AspNetCore.Http.Json.JsonOptions has additional ramifications as it would also change behavior of outbound http calls from an aspnet core mvc api to other services.

Describe the solution you'd like

• The Microsoft.AspNetCore.OpenApi packages should support json options configuration independently of the overall Microsoft.AspNetCore.Http.Json.JsonOptions configuration.
• Continuing to default the values to match those of the service container's Http.Json.JsonOptions would be acceptable, but the AddOpenApi() service collection extension methods should support specifying the options to use without requiring a global default change to the behavior of the application

Additional context

No response

[captainsafia]

Closing this out as a dupe of the related issue.

At this point in time, the strategy is to depend on the JsonOptions defined in the HTTP layer as the source of truth since it's flexible across multiple layers of the stack.

If we were to make a change here, it would be to respect HTTP's options in the MVC layer but that comes with its own baggage.

[RyanThomas73]

@captainsafia Can you provide a work around then that would allow us to use this package since we are currently blocked by this?

As stated in my original post the request is not to stop using the JsonOptions defined in the http layer but to allow us to specify them independently of the global/app wide dependency container options.

[captainsafia]

What's an example of a serialization option you want to configure independent of the global config?

[RyanThomas73]

For example it's pretty common in several of our pre-existing apps to have the mvc serialization options using JsonStringEnumConverter and our global http json options to not be using that converter for various downstream 3rd party api calls.

[RyanThomas73]

Also for reference, here's a relatively minimal example update that would allow such an override to be configured while still using the http json options type.

OpenApiServiceCollectionExtensions.cs

/// <summary>
/// Adds OpenAPI services related to the given document name to the specified <see cref="IServiceCollection"/> with the specified options.
/// </summary>
/// <param name="services">The <see cref="IServiceCollection"/> to register services onto.</param>
/// <param name="documentName">The name of the OpenAPI document associated with registered services.</param>
/// <param name="configureOptions">A delegate used to configure the target <see cref="OpenApiOptions"/>.</param>
/// <example>
/// This method is commonly used to add OpenAPI services to the <see cref="WebApplicationBuilder.Services"/>
/// of a <see cref="WebApplicationBuilder"/>, as shown in the following example:
/// <code>
/// var builder = WebApplication.CreateBuilder(args);
/// builder.Services.AddOpenApi("MyWebApi", options => {
///     // Add a custom schema transformer for decimal types
///     options.AddSchemaTransformer(DecimalTransformer.TransformAsync);
/// });
/// </code>
/// </example>
public static IServiceCollection AddOpenApi(this IServiceCollection services, string documentName, Action<OpenApiOptions> configureOptions, Microsoft.AspnetCore.Http.Json.JsonOptions? jsonOptionsOverride = null)
{
    ArgumentNullException.ThrowIfNull(services);
    ArgumentNullException.ThrowIfNull(configureOptions);

    // We need to register the document name in a case-insensitive manner to support case-insensitive document name resolution.
    // The document name is used to store and retrieve keyed services and configuration options, which are all case-sensitive.
    // To achieve parity with ASP.NET Core routing, which is case-insensitive, we need to ensure the document name is lowercased.
    var lowercasedDocumentName = documentName.ToLowerInvariant();

    services.AddOpenApiCore(lowercasedDocumentName, jsonOptionsOverride);
    services.Configure<OpenApiOptions>(lowercasedDocumentName, options =>
    {
        options.DocumentName = lowercasedDocumentName;
        configureOptions(options);
    });
    return services;
}

private static IServiceCollection AddOpenApiCore(this IServiceCollection services, string documentName, Microsoft.AspnetCore.Http.Json.JsonOptions? jsonOptionsOverride)
{
    services.AddEndpointsApiExplorer();

    if (jsonOptionsOverride is null)
    {
        services.AddKeyedSingleton<OpenApiSchemaService>(documentName);

        // Required to support JSON serializations
        services.TryAddEnumerable(ServiceDescriptor.Singleton<IConfigureOptions<JsonOptions>, OpenApiSchemaJsonOptions>());
    }
    else
    {
        jsonOptionsOverride.SerializerOptions.TypeInfoResolverChain.Insert(0, OpenApiJsonSchemaContext.Default);

        services.AddKeyedSingleton<OpenApiSchemaService>(documentName, (serviceProvider, _) =>
        {
            return new OpenApiSchemaService(
                documentName,
                Options.Create(jsonOptionsOverride),
                serviceProvider.GetRequiredService<IOptionsMonitor<OpenApiOptions>>()
            );
        });
    }

    services.AddKeyedSingleton<OpenApiDocumentService>(documentName);
    services.AddKeyedSingleton<IOpenApiDocumentProvider, OpenApiDocumentService>(documentName);

    // Required for build-time generation
    services.AddSingleton<IDocumentProvider, OpenApiDocumentProvider>();
    // Required to resolve document names for build-time generation
    services.AddSingleton(new NamedService<OpenApiDocumentService>(documentName));
    return services;
}