ITADN

[Bug]: Example Null-Handling Seems Inverted

#3801Closedpinkfloydx33 创建于 2026-02-18
bug
P
pinkfloydx33commented
### Describe the bug I was actually happy to see #3793 as this was a minor gap for us in the .NET 10 upgrade where we had some examples that were explicitly/intentionally written to the API Spec as `null`. However moving to the new package 10.1.4 seems to exhibit strange behavior. I am only allowed to write a `null` example to the document if the data type is `JsonSchemaType.String` but _not_ `JsonSchemaTypeString | JsonSchemaType.Null`. https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/8ad6682f15c4df3a3ad2ad8815b9af914af20b1f/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsExampleHelper.cs#L16-L23 This seems inverted! I can set `example=null` on a **non-nullable** `string`, but _not_ on a **nullable** `string?` It also seems a bit funny that it's limited to strings and not any nullable type ### Expected behavior At the very least I would expect to be able to set the example value to `null` if the property itself supports being null i.e. with `JsonSchemaType.Null | JsonSchemaType.String` Though I probably would not limit this to just strings at all! Perhaps something like this could suffice for any type of property: ```csharp var type = schema?.ResolveType(schemaRepository); if (type is { } value && value.HasFlag(JsonSchemaType.Null) && string.Equals(exampleString, "null")) { return JsonNullSentinel.JsonNull; } // rest of method ``` ### Actual behavior Cannot write `"example": null` to document if schema resolves to `JsonSchemaTypeString | JsonSchemaType.Null` Cannot write `"example": null` for numeric or other properties that have the `JsonSchemaType.Null` flag ### Steps to reproduce Consider this data type: ```csharp public sealed class MyType { /// <example>null</example> [Required] public string Ex0 { get; set; } = null!; /// <example>null</example> public string? Ex1 { get; set; } /// <example>null</example> public Guid Ex2 { get; set; } /// <example>null</example> public Guid? Ex3 { get; set; } /// <example>null</example> public int Ex4 { get; set; } /// <example>null</example> public int? Ex5 { get; set; } /// <example>3</example> public int? Ex6 { get; set; } } ``` The API Specification generated will produce | Field | Expected Example | Actual Example | Correct | | -- | -- | -- | -- | | `Ex0` | omitted | `"example": null` | :x: | | `Ex1` | `"example": null` | omitted | :x: | | `Ex2` | omitted | `"example": null` | :x: | | `Ex3` | `"example": null` | omitted | :x: | | `Ex4` | omitted | omitted | :white_check_mark: | | `Ex5` | `"example": null` | omitted | :x: | | `Ex6` | `"example": 3` | `"example": 3` | :white_check_mark: | ### Exception(s) (if any) _No response_ ### Swashbuckle.AspNetCore version 10.1.4 ### .NET Version 10 ### Anything else? As a work-around, you can write the literal value of `JsonNullSentinel.NullValue` as your example and it will get converted just fine: ```csharp public sealed class MyType { /// <example>openapi-json-null-sentinel-value-2BF93600-0FE4-4250-987A-E5DDB203E464</example> public string? Ex1 { get; set; } } ``` However that is a bit heavy handed and likely an implementation detail!
关闭于 2026-03-10 13 条评论