[Bug]: Issue/Regression related to nullable enums and reference types in v10

[zotanmew]

Describe the bug

Before v10, I was configuring nullability as follows:

builder.Services.AddSwaggerGen(o =>
{
    options.SupportNonNullableReferenceTypes();
    options.UseAllOfToExtendReferenceSchemas();
    options.UseAllOfForInheritance();
}

This produced correct nullability annotations for enums as well as reference types (including other object schemas) using nullable: true.

v10 seems to have changed both how nullability is annotated, as well as how references work. The above setup now produces the nonsensical combination of type: "null" with allOf: [...], causing type definition source generators to go haywire (e.g. the typescript one produces an intersection of null and the referenced object type definition, which collapses into never).

I tried to fix this with a schema filter, however I came to the conclusion that this is not possible to model with the new way references are represented (as the Type property is passed through to the reference target, which is obviously not nullable in this context).

The Microsoft.AspNetCore.OpenApi generator does not have this issue, though it comes with a myriad of other problems for our codebase, so I'd love for this to get addressed / to get any leads for a possible workaround.

Thank you for this awesome project, and should I have missed anything obvious, apologies in advance.

[martincostello]

Thanks for reporting this issue.

Could you provide a minimal reproducible example as a GitHub repository that demonstrates the issue you're experiencing so we can look into this further?

From the description it sounds like you're generating an OpenAPI 3.1 document (which is not the intended default, which is 3.0). If you've opted-in to 3.1, then it might not be an issue with Swashbuckle, but with the tooling you're using being able to understand 3.1.

If you're using 3.0, then it sounds like there's a bug, but I'll need a repro to debug to be able to see where the problem might be (it could be a bug in Microsoft.OpenApi, for example).

[zotanmew]

Heya & thanks for the quick reply, I am indeed generating a 3.1 document. Minimal repro:

using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(o =>
{
	o.SupportNonNullableReferenceTypes();
	//o.UseInlineDefinitionsForEnums(); // <-- fixes nullable enums, causes the schema to generate for Nullable<TEnum> instead of TEnum
	o.UseAllOfToExtendReferenceSchemas();
	o.UseAllOfForInheritance();
});
builder.Services.AddMvc();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
	app.MapOpenApi();
	app.UseSwagger(o => o.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1);
	app.UseSwaggerUI();
}

app.MapGet("/weatherforecast", ([FromBody] Test1 a) => { })
   .WithName("GetWeatherForecast");

app.Run();

class Test1
{
	public Test2? test { get; set; }
	public TestEnum? en   { get; set; }
}

class Test2
{
	public string    abcd { get; set; }
}

enum TestEnum
{
	One,
	Two,
	Three
}

openapi-typescript generates nonsense, swagger-ui also looks strange at best, and intuitively something with type: "null" having extra properties doesn't seem to make sense at first glance - I'd expect oneOf: [{type: "null"}, {$ref: "..."}] (for the object case) / type: ["null", "integer"] (for the enum case), which does match the behavior of the MS generator (which both the ts generator and swagger-ui seem to handle correctly, and, at least to me, makes intuitive sense).

[martincostello]

OK thanks, I'll look into it when I get some time.

Sounds like I didn't properly update the model code to deal with this case when updating to the new way nullability works in Microsoft.OpenApi v2.

[zotanmew]

Thank you so much! I’ve switched to generating 3.0 documents for now, so I even have a workaround now.

[martincostello]

@zotanmew Just looking at this now.

Is this the incorrect OpenAPI schema you get with your repro (I've renamed a few things for clarity in my local equivalent):

  "components": {
    "schemas": {
      "Child": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "Parent": {
        "type": "object",
        "properties": {
          "child": {
            "type": "null",
            "allOf": [
              {
                "$ref": "#/components/schemas/Child"
              }
            ]
          },
          "category": {
            "enum": [
              0,
              1,
              2
            ],
            "type": [
              "null",
              "integer"
            ],
            "format": "int32"
          }
        },
        "additionalProperties": false
      }
    }
  }

and what should be generated would be:

  "components": {
    "schemas": {
      "Child": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "Parent": {
        "type": "object",
        "properties": {
          "child": {
-           "type": "null",
-           "allOf": [
-             {
-               "$ref": "#/components/schemas/Child"
-             }
-            ]
+           "oneOf": [
+             {
+               "type": "null"
+             },
+             {
+               "$ref": "#/components/schemas/Child"
+             }
+           ]
          },
          "category": {
            "enum": [
              0,
              1,
              2
            ],
            "type": [
              "null",
              "integer"
            ],
            "format": "int32"
          }
        },
        "additionalProperties": false
      }
    }
  }

[zotanmew]

Yep, that looks correct!

[martincostello]

@zotanmew I think I've fixed the scenario above in #3680 (the relevant commit is ee23bac).

Would you be able to test your application with those changes (you can get the NuGet packages from the GitHub Actions CI workflow once it completes) and see whether the schema and your tooling issues are resolved?

[zotanmew]

Looks like everything works correctly now, thank you so much!