OpenApi ignores JsonNumberHandling.WriteAsString

[adrianm64]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

When a property has the attribute JsonNumberHandling(JsonNumberHandling.AllowReadingFromString|JsonNumberHandling.WriteAsString), OpenApi still describes the property with the native type and not a string

Expected Behavior

When using JsonNumberHandling.WriteAsString I expect the OpenApi specification to report the propery as string

"prop": {
    "type": "string",
 }

Steps To Reproduce

1. Create a new default asp.net webapi for dotnet 9.
2. Run the project and navigate to /openapi/v1.json
3. The temperatureC property is listed as integer:

"temperatureC": {
    "type": "integer",
     "format": "int32"
},  

4. In weatherforcast.cs add an attribute to the temperatureC property

[JsonNumberHandling(JsonNumberHandling.AllowReadingFromString|JsonNumberHandling.WriteAsString)]
public int TemperatureC { get; set; }

5. Run the project and navigate to /weatherforecast and see temperatureC is a string.

[{"date":"2024-11-12","temperatureC":"11","temperatureF":51,"summary":"Balmy"},{"date":"2024-11-13","temperatureC":"3","temperatureF":37,"summary":"Warm"}}

6. Navigate to /openapi/v1.json
7. The temperatureC property is still listed as an integer:

"temperatureC": {
    "type": "integer",
    "format": "int32"
},  

Exceptions (if any)

No response

.NET Version

9.0.100-rc.1.24452.12

Anything else?

A workaround is to add a SchemaTransformer like

internal sealed class JsonNumberHandlerSchemaTransformer : IOpenApiSchemaTransformer
{
    public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)
    {
        var properties = context.JsonTypeInfo.Type.GetProperties(BindingFlags.Public | BindingFlags.Instance)
                                .Where(prop => prop.GetCustomAttribute<JsonNumberHandlingAttribute>()?.Handling.HasFlag(JsonNumberHandling.WriteAsString) ?? false)
                                .Select(prop => prop.GetCustomAttribute<JsonPropertyNameAttribute>()?.Name ?? 
                                                context.JsonTypeInfo.Options.PropertyNamingPolicy?.ConvertName(prop.Name) ??
                                                prop.Name)
                                .Where(schema.Properties.ContainsKey);

        foreach (var property in properties)
        {
            schema.Properties[property].Type = "string";
        }

        return Task.CompletedTask;
    }
}

but this is using reflection and probably missing some other details.

[captainsafia]

@adrianm64 Thanks for filing this issue and sharing the workaround that you had success with!

@mikekistler This is one of those scenarios where our explicit type mappings for primitives gets us into trouble. Should we exempt integer types from this? We might be able to do so in .NET 10 with the JSON schema generated directly from STJ.

[mikekistler]

I'm observing the following behavior:

Property has JsonNumberHandling	produces a schema with type
AllowReadingFromString	[ "string", "integer" ]
AllowReadingFromString|WriteAsString	[ "string", "integer" ]
Strict	"integer"

Note that "AllowReadingFromString" is the default for Web applications.

@captainsafia I don't think exempting integer is the solution, because the same behavior occurs for double and likely any other "number" type.

I'm not really sure what the solution is here, since OpenAPI v3.0.x does not permit type to be an array. Perhaps the only "correct" thing to do is to omit "type" whenever the type from STJ is an array with more than one element (still handling "null" specially). But that might be more painful than the current behavior.

[captainsafia]

Thanks for verifying the current behavior!

@captainsafia I don't think exempting integer is the solution, because the same behavior occurs for double and likely any other "number" type.

Correct -- if we went down this route, we'd have to avoid our primitive-type based lookup for everything.

I'm not really sure what the solution is here, since OpenAPI v3.0.x does not permit type to be an array. Perhaps the only "correct" thing to do is to omit "type" whenever the type from STJ is an array with more than one element (still handling "null" specially). But that might be more painful than the current behavior.

Perhaps this is something we can bundle around the 3.1 support issue (#58619)? We should be able to use array types there and generate a more accurate schema.