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
- Revert #3377 Manually revert changes from #3377. Resolves #3425. — committed to domaindrivendev/Swashbuckle.AspNetCore by martincostello a year ago
- Revert #3377 Manually revert changes from #3377. Resolves #3425. — committed to LoadsAForks/Swashbuckle.AspNetCore by martincostello a year ago
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:
Nullable<T>, so can have a value or benullTcan be a reference to an instance of that type ornull.T) or not (T?)!, e.g.public T Foo { get; set; } = null!;requiredand the developer must initialize the property when writing the code.JSON has:
nullor 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:
And I POST JSON to an endpoint that receives a
MyModelthat looks like this:Then at runtime, my endpoint will get the following values:
required, it wasn’t specified in the request and isn’t enforced at runtime, so it just has the default value for anintof0.Bshould 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 ofnullas specified in the type’s construction.Callowsnulland is specified, so has a value ofnull.Dallowsnullbut a non-null value is specified in the JSON, so it receives the value of42.This all effectively means we have two different definitions of what “required” means - C#'s and OpenAPI’s.
In OpenAPI terms:
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
intandint?are considered different types in OpenAPI 3.1. The former can never have anullvalue 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:
This is where the
IntandNullableInttypes (schemas) come into play.B,DandFaren’tIntthat are nullable, they’reNullableInt- butDandFare 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?