OpenApi components schema $ref may not correct

[niltor]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

My Cshrap models:

public class SystemPermissionGroup : EntityBase
{
    /// <summary>
    /// 
    /// </summary>
    [MaxLength(30)]
    public required string Name { get; set; }
    /// <summary>
    /// 
    /// </summary>
    [MaxLength(1000)]
    public string? Description { get; set; }

    public ICollection<SystemPermission> Permissions { get; set; } = [];

    public ICollection<SystemRole> Roles { get; set; } = [];
}

OpenApi Json:

   "SystemPermissionGroup": {
        "required": [
          "name"
        ],
        "type": "object",
        "properties": {
          "name": {
            "maxLength": 30,
            "type": "string",
            "description": "权限名称标识"
          },
          "description": {
            "maxLength": 1000,
            "type": [
              "null",
              "string"
            ],
            "description": "权限说明"
          },
          "permissions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SystemPermission"
            }
          },
          "roles": {
            "$ref": "#/components/schemas/SystemUserInfoDto/properties/systemRoles/items/properties/permissionGroups/items/properties/permissions/items/properties/group/properties/roles"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "createdTime": {
            "type": "string",
            "format": "date-time"
          },
          "updatedTime": {
            "type": "string",
            "format": "date-time"
          },
          "isDeleted": {
            "type": "boolean"
          }
        }
      },

see the roles $ref:

 "roles": {
    "$ref": "#/components/schemas/SystemUserInfoDto/properties/systemRoles/items/properties/permissionGroups/items/properties/permissions/items/properties/group/properties/roles"
  }

💀💀 What's this?

But permissions schema is correct.

And I did have a SystemUserInfoDto model:

public class SystemUserInfoDto
{
    /// <summary>
    /// user name
    /// </summary>
    [MaxLength(30)]
    public required string UserName { get; set; }

    public Guid Id { get; set; }
    public ICollection<SystemRole> SystemRoles { get; set; } = [];
}

Expected Behavior

the roles schema should be like:

"roles": {
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/SystemRole"
  }
},

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

.net10.rc1 .net10.rc2

Anything else?

No response

[MihuBot]

I'm a bot. Here are possible related and/or duplicate issues (I may be wrong):

• .NET 9 OpenAPI produces lots of duplicate schemas for the same object #58968
• OpenAPI with two collections of same type generates weird internal ref #60931
• OpenApi: Multiple array properties of the same type do not get the correct type reference #63353
• Incorrect OpenAPI generation #63460
• OpenApi document generation does not generate reference to array items #63735

[niltor]

@martincostello

Considering that the official version of .NET 10 is about to be released, is it possible to fix this issue recently?
Or at least avoid it.

This is very serious because an incorrect Swagger will break all subsequent tools and workflows that depend on the OpenAPI doc.

[captainsafia]

@niltor Do you have a minimal repro of the API surface area that caused this issue? What is the SystemRole type?

[niltor]

@captainsafia

It took some time to reproduce the problem using a simple project, but I still don't know why this problem occurs.

IssueSample

[desjoerd]

This issue feels very similar to #63503.

A new recursion and circular reference puzzle to solve.

@niltor could you only reproduce it with this very large model?
Maybe it's reproducible with a smaller model by changing the order of the properties.

[desjoerd]

With a lot of trial and error and removing properties from your repro, this is the most minimal reproduce of the issue:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();
app.MapPost("/issue", (Root root) => TypedResults.Ok());

app.Run();

public class Root
{
    public ReferencedCircularItem Item { get; set; }
    public ICollection<ReferencedCircularItem> ItemArray { get; set; }
}

public class ReferencedCircularItem
{
    public ICollection<ReferencedCircularItem> ItemArray { get; set; }
}

When Root.Item and Root.ItemArray are in a different order the issue does not occur.

Resulting openapi:

{
  "openapi": "3.1.1",
  "info": {
    "title": "OpenApiIssue | v1",
    "version": "1.0.0"
  },
  "paths": {
    "/issue": {
      "post": {
        "tags": [
          "OpenApiIssue"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Root"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ReferencedCircularItem": {
        "type": "object",
        "properties": {
          "itemArray": {
            "$ref": "#/components/schemas/Root/properties/item/properties/itemArray"
          }
        }
      },
      "Root": {
        "type": "object",
        "properties": {
          "item": {
            "$ref": "#/components/schemas/ReferencedCircularItem"
          },
          "itemArray": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferencedCircularItem"
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "OpenApiIssue"
    }
  ]
}

Now it's time to have some fun debugging the resolving of references coming from the JsonSchemaExporter.