Swagger in unable to produce example values for nullable properties with OpenAPI in .NET 10

[ctyar]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

The following model with .NET 10, Microsoft.AspNetCore.OpenApi and Swagger

public class TodoRequest
{
    [Required]
    public string? Description { get; set; } = null!;
    public DateTimeOffset? DueDate { get; set; }
    [Required]
    public Priority? Priority { get; set; }
    public List<string>? Tags { get; set; } = [];
}

Would result in the following example value:

Note the nulls for Description and DueDate properties in the Example Value section of the screenshot.

Expected Behavior

This was working in .NET 9 and would result in the following example value:

Steps To Reproduce

Clone the following repo and run the project.
You can also change the TargetFramework to net9.0 to see the previous behaviour.
https://github.com/ctyar/Playground/tree/dotnet_10_openapi

Exceptions (if any)

No response

.NET Version

10.0.100-preview.3.25177.4

Anything else?

I believe this is happening because of the move from openapi 3.0.1 to openapi 3.1.1.
It seems the new specification handles nulls differently, so there was a change in the openapi JSON that Microsoft.AspNetCore.OpenApi produces.

For example, the sample above produces the following JSON specification for the Description property:

"description": {
            "type": [
              "null",
              "string"
            ]
          },

If we change the order of members in the type array to:

"description": {
            "type": [
              "string",
              "null"
            ]
          },

Swagger is able to produce the correct example.

[captainsafia]

@ctyar Thanks for filing this issue.

I believe what you are seeing might be a variant of swagger-api/swagger-ui#9056. It seems that Swagger UI is not really good at handling the [type, null] value supported by OpenAPI 3.1. There's a few other issues related to null-handled in Swagger UI with OpenAPI 3.1 so I think this is an external issue worth filing there.

[ctyar]

@captainsafia I've created an issue in SwaggerUI repo: swagger-api/swagger-ui#10388
By the way, the same thing happens in Scalar https://client.scalar.com:

and ReDoc https://redocly.github.io/redoc/:

Sample:

{
  "openapi": "3.1.1",
  "info": {
    "title": "Playground | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:5150"
    }
  ],
  "paths": {
    "/todos": {
      "post": {
        "tags": [
          "TodoEndpoints"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TodoRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "NullableOfPriority": {
        "enum": [
          "Low",
          "Medium",
          "High",
          "Critical",
          null
        ]
      },
      "TodoRequest": {
        "required": [
          "description",
          "priority"
        ],
        "type": "object",
        "properties": {
          "description": {
            "type": [
              "null",
              "string"
            ]
          },
          "dueDate": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          },
          "priority": {
            "$ref": "#/components/schemas/NullableOfPriority"
          },
          "tags": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "TodoEndpoints"
    }
  ]
}

[ctyar]

This issue is now fixed in Swagger UI 5.20.4