Swashbuckle.AspNetCore: [Bug]: Behaviour change in 8.1.2 for nullable enums

Describe the bug

After updating from 8.1.1 to 8.1.2, there is an issue with type names for nullable enums.

It appears that all enums that are used as nullable values, e.g. class Request { MyEnum? Value { get; set; } } have their schema name changed in the generated resulting OpenAPI spec from MyEnum to MyEnumNullable.

This breaks client code generation that relies on the type names to match C# source, e.g. when using NSwagGen with GenerateDtoTypes:false, the generated client code fails to compile because it references a non-existing MyEnumNullable.

Expected behavior

Schema names should match C# source names

Actual behavior

Schema names are altered.

Steps to reproduce

No response

Exception(s) (if any)

No response

Swashbuckle.AspNetCore version

8.1.2

.NET Version

9.0.5

Anything else?

No response

About this issue

  • Original URL
  • State: closed
  • Created a year ago
  • Reactions: 4
  • Comments: 15 (1 by maintainers)

Commits related to this issue

Most upvoted comments

This change was reverted as part of the 8.1.3 release, which is now available from NuGet.org.

“soon” is all I can give you. Rollback to 8.1.1 if you’re having problems.

I think the confusion stems from the disconnect between the way C# works and the way JSON documents work. It’s possible that even my understanding of it as given below is also confused, so if I’m incorrect here then let me know. 😄

C# has:

  • Properties are always present if they are defined by the code.
  • A property’s type can be nullable:
    • Either because it is Nullable<T>, so can have a value or be null
    • When nullable reference types are not used, a property of type T can be a reference to an instance of that type or null.
    • When nullable reference types are used, it can be marked as non-null (T) or not (T?)
    • Nullable reference types are a compile-time feature - they do not enforce a lack of null, as it can be overridden by the developer using !, e.g. public T Foo { get; set; } = null!;
  • A property can be required and the developer must initialize the property when writing the code.

JSON has:

  • A property can be optional and omitted from a JSON document entirely.
  • A property can be required and must be present in the JSON document to be valid.
  • A property can allow its value to be null or not.

Depending on your specific circumstances, this can mean you get nulls when you don’t expect them and vice versa.

If I have a model as such:

#nullable enable

public class MyModel
{
    public required int A { get; set; }

    public string B { get; set; } = null!;

    public int? C { get; set; }

    public int? D { get; set; }
}

And I POST JSON to an endpoint that receives a MyModel that looks like this:

{
  "C": null,
  "D": 42
}

Then at runtime, my endpoint will get the following values:

A = 0
B = null
C = null
D = 42
  • Despite A being required, it wasn’t specified in the request and isn’t enforced at runtime, so it just has the default value for an int of 0.
  • While B should not be null because of nullable reference types, it isn’t enforced by the JSON serializer and isn’t present in the JSON document, so it has the value of null as specified in the type’s construction.
  • C allows null and is specified, so has a value of null.
  • D allows null but a non-null value is specified in the JSON, so it receives the value of 42.

This all effectively means we have two different definitions of what “required” means - C#'s and OpenAPI’s.

In OpenAPI terms:

  • “required” means the property must be present in the JSON document to be valid.
  • “nullable” means if the property is present, its value may be null.

We try to map the relevant C# concepts to these OpenAPI concepts in the most appropriate way.


This part I’m less certain on, but my understanding is that int and int? are considered different types in OpenAPI 3.1. The former can never have a null value in its set of possible values, the latter can - this is unrelated to whether the value is present in the JSON document (i.e. required).

Here’s an attempt to illustrate this with a C# model:

public class MyModel
{
    // Cannot have a null value, may be absent from the JSON document.
    // Cannot tell the difference between an explicit value of 0 or not being present.
    public int A { get; set; }

    // Can have an explicit null value, may be absent from the document
    // Cannot tell the difference between an explicit value of null or not being present.
    public int? B { get; set; }

    // Cannot have a null value, must be present in the document.
    // If enforced by the serializer, a value of `0` means it was explicitly specified in the document.
    [Required]
    public int C { get; set; }

    // Can have a null value, must be present in the document.
    // If enforced by the serializer, a value of `null` means it was explicitly specified in the document.
    [Required]
    public int? D { get; set; }

    // Cannot have a null value, must be present in the document.
    // If enforced by the serializer, a value of `0` means it was explicitly specified in the document.
    public required int E { get; set; }

    // Can have a null value, must be present in the document.
    // If enforced by the serializer, a value of `null` means it was explicitly specified in the document.
    public required int? F { get; set; }
}

This is where the Int and NullableInt types (schemas) come into play. B, D and F aren’t Int that are nullable, they’re NullableInt - but D and F are also required.

If .NET/C# eventually gets built-in support for discriminated unions, then “was this specified in the JSON document” might get much easier to determine at runtime.


I hope this makes at least some sense and aids understanding - I do agree that it’s tricky to separate the concepts if you’re familiar with C# and then come to OpenAPI later and expect the C# concepts to flow nicely into the OpenAPI ones.

This comment is mostly a stream of consciousness reply to https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/3425#issuecomment-2934204030 😅

Maybe some additional thoughts on this because as I understand the feature will defintly come back to us. First I was really shocked by the change (no matter if it will be reverted) and then I thought a bit about it and I’m more confused than ever. Currently it feels as if C#/.NET will never really support the full OpenAPI specs.

Let’s consider a C# model with a simple public EnumX X {get;set;}. In the default behavior this will not be required in the generated OpenAPI schema - to do so, the RequiredAttribute has to be added. But actually .NET can’t do this: the property X is defined on the model class and always be there. Considering OpenAPI a client can now send nothing for X and it seems that X may be missing in any JSON from the server occasionally. But this will never be the case: X is always there and if this is not send it will get its default enum value.

Considering XML there is on (de)serialization the option to add some additional “isSet…” field (or property - don’t remember exactly, long time ago) which handles this behavior and allows to suppress adding a property to the serialized state - or report that its missing. Nevertheless this must be handled explicitly in code - the enum property is still always set. I did not find such a feature in System.Text.Json - maybe Json.Net have it but at least for us this is not an option.

So back to the roots: aren’t all .NET class properties required by principle? What about public EnumX? X {get;set;}? This is also required but may be null in addition to the enumeration values. Sending nothing from a client will end up in null without any further information. Allowing an additional string enum value "null" as suggested makes it even worse in my (current state of thinking) opinion - at least if you might someday have an enum value “null” for yourself. OneOf at least feels like a much better solution - I did’t check it the API generator we use would handle it as expected.

So to summarize: to interpret a regular .NET property correctly it should always be required in OpenAPI. If additional OpenAPI behavior is required to map to .NET additional attributes (like Required today) will be needed in addition the option to check dedicated behavior e.g. to see the difference between null and not set at all in JSON (or undefined if created from JavaScript).

It wasn’t a major version bump because it was an unintentional change in behaviour as already stated.

Same issues. Will stay with 8.1.1. This is a breaking change, so should be 8.2 or 9.0!

This update has affected our codebase in the same manner, and has broken our frontend build layer which relies on the type names in the Swagger file remaining constant, so that generated TypeScript remains compatible with references in static application code.

We use Axios for OpenAPI code generation from a Swagger.json file.

Is there a way to opt out of this behaviour in 8.1.2 config options? Or should we just wait until this is opt-in on a future version?