[V3] Incorrect reference types for classes with more than one collection properties of the same reference type

[asankaf]

Describe the bug
For response models that contain multiple collection properties referring to the same collection type, the generated document contains invalid schema references for all but one of those properties.

OpenApi File To Reproduce
SampleOpenApi_v1.0.json

Expected behavior
All the properties should point to the correct schema reference type

Screenshots/Code Snippets

/* Response Models */
public class Account
{
    public int Id { get; init; }
    public required string Name { get; init; }
}

public class LegalEntity
{
    public required ICollection<Account> Balances { get; init; }
    public required ICollection<Account> Assets { get; init; }
    public required ICollection<Account> Equities { get; init; }
    public required ICollection<int> DeletedAccounts { get; init; }
}

/* Api */
[Route("api/v{version:apiVersion}/accounts")]
public class LegalEntitiesController : ApiControllerBase
{
    /// <summary>
    /// Get legal entities
    /// </summary>
    /// <returns>The <see cref="LegalEntity"/></returns>
    [ApiVersion("1.0")]
    [ApiVersion("2.0")]
    [HttpGet(Name = nameof(GetLegalEntityAccounts))]
    [ProducesResponseType(typeof(IEnumerable<LegalEntity>), StatusCodes.Status200OK)]
    [ProducesDefaultResponseType]
    public IEnumerable<LegalEntity> GetLegalEntityAccounts()
    {
        return Enumerable.Range(1, 5).Select(index => new LegalEntity
        {
            Balances =
            [
                new Account { Id = index + 1, Name = "Balance 1" },
                new Account { Id = index + 2, Name = "Balance 2" }
            ],
            Assets =
            [
                new Account { Id = index + 3, Name = "Asset 1" },
                new Account { Id = index + 4, Name = "Asset 2" }
            ],
            Equities =
            [
                new Account { Id = index + 5, Name = "Equity 1" },
                new Account { Id = index + 6, Name = "Equity 2" }
            ],
            DeletedAccounts = [index + 7, index + 8]
        });
    }
}

Invalid schema reference types in the generated open api document

{
  ...
  "components": {
    "schemas": {
     ...
     "LegalEntity": {
       "required": [
         "balances",
         "assets",
         "equities",
         "deletedAccounts"
       ],
       "type": "object",
       "properties": {
         "balances": {
           "type": "array",
           "items": {
             "$ref": "#/components/schemas/Account"
           }
         },
         "assets": {
           "type": "array",
           "items": {
             "$ref": "#/components/schemas/#/items/properties/balances/items"
           }
         },
         "equities": {
           "type": "array",
           "items": {
             "$ref": "#/components/schemas/#/items/properties/balances/items"
           }
         },
         "deletedAccounts": {
           "type": "array",
           "items": {
             "type": "integer",
             "format": "int32"
           }
         }
       }
     },
    }
  }
}

I have created a sample project here to reproduce the issue.

[darrelmiller]

@captainsafia We looked through this and we are not sure where the source of this error is coming from. It appears that the $ref in balances is generated correctly, but assets and equities is wrong. It feels like the wrong Id value is being provided to the OpenAPIReference when being constructed.

[asankaf]

@darrelmiller as you said, 'balances' points to the correct schema type while the others that are of the same reference type do not. If I use Swashbuckle.AspNetCore package, it generates the $ref correctly for all 3 of them.

[asankaf]

@darrelmiller any timeline on a fix to this issue? It seems like a very easy to recreate bug to me and if you look at the source I attached, it's quite basic and nothing complicated going on there. So if I am guessing, this seems like an issue in "Microsoft.AspNetCore.OpenApi" package.

[MaggieKimani1]

@captainsafia can you please help confirm if this is an AspNetCore.OpenApi package issue?

[captainsafia]

@MaggieKimani1 This came up in one of our online syncs a while back. TL;DR: this is an issue in Microsoft.AspNetCore.OpenApi for .NET 9 that was resolved in servicing. However, variants of this bug still exist with the new reference resolution in .NET 10. That's tracked in #2062.

[RachitMalik12]

Closing as it is fixed in 9.0.400 release of ASP.NET Core: dotnet/aspnetcore#60381
OpenAPI.NET will use #2062 to track other reference related issues for future releases.
cc: @captainsafia

[asankaf]

I have checked this with the latest 9.0.400 release of ASP.NET Core. The original issue is not yet fixed. The collection references are not even pointing to a type anymore. This is what the generated open api document looks like now.

CC: @RachitMalik12 @captainsafia @MaggieKimani1

{
  ...
  "components": {
    "schemas": {
     ...
     "LegalEntity": {
       "required": [
         "balances",
         "assets",
         "equities",
         "deletedAccounts"
       ],
       "type": "object",
       "properties": {
         "balances": {
           "type": "array",
           "items": {
             "$ref": "#/components/schemas/Account"
           }
         },
         "assets": {
           "type": "array",
           "items": { }
         },
         "equities": {
           "type": "array",
           "items": { }
         },
         "deletedAccounts": {
           "type": "array",
           "items": {
             "type": "integer",
             "format": "int32"
           }
         }
       }
     },
    }
  }
}

The sample repo is also now updated.