OpenAPI does not generate reference to self when returning arrays in controllers

[iskandersierra]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

When a controller's action returns a collection type like List<Item> or a class that contains such collection, and Item contains a property of type List<Item>, the OpenAPI spec generator generates an untyped array for the self-referencing property.

Issue #61408 seems to be related but with a more complex setup

Expected Behavior

I expected that the OpenAPI spec generator generated a typed array where the items had a "$ref" to the same model.

Steps To Reproduce

See repro at: https://github.com/iskandersierra/OpenApiSelfReferenceRepro

The models are the following:

public class Level1
{
    public IReadOnlyList<Level1> Level1s { get; set; } = [];
}

And the Controller code is:

[ApiController]
[Route("[controller]")]
public class LevelController : ControllerBase
{
    [HttpGet(Name = "GetLevels")]
    public IReadOnlyList<Level1> GetLevels()
    {
        return new();
    }
}

However the schemas generated by OpenAPI are not correct:

{
    "Level1": {
        "type": "object",
        "properties": {
            "level1s": {
                "type": "array",
                "items": { }
            }
        }
    }
}

And it should be:

{
    "Level1": {
        "type": "object",
        "properties": {
            "level1s": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/Level1" }
            }
        }
    }
}

Some facts:

• It doesn't matter which type of collection we return in the controller, the issue is always the same.
• If the controller returns Level1 instead of IReadOnlyList<Level1>, the schema is generated correctly.`
• If there is a second action returning the Level1 type, the schema gets the Level1 duplicated as Level12, one gets generated correctly and the other one incorrectly, depending on the order of the actions in the controller.

Exceptions (if any)

No exception is detected, just the wrong schema specification.

.NET Version

9.0.203

Anything else?

Project 'OpenApiSelfReferenceRepro' has the following package references
   [net9.0]: 
   Top-level Package                   Requested   Resolved
   > Microsoft.AspNetCore.OpenApi      9.0.4       9.0.4

[martincostello]

This looks like a duplicate of #61407.

[iskandersierra]

Not exactly, but agreed that it is related

[sorcerb]

Or this #61139

[iskandersierra]

I had to create a middleware for the /openapi/v1.json to manually parse/modify/re-serialize the OpenAPI spec. I leave my solution here as a workaround, if anyone needs a quick fix for now.

WARNING: This solution is not production ready with respect to memory management, because I'm serializing the whole OpenAPI spec to memory, no caching is being used, etc.

NOTE: A solution using Schema Transformers didn't work. Either the replaced reference was removed or a StackOverflowException was thrown.

public class FixProjectsOpenApiMiddleware : IMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        if (context.Request.Path == "/openapi/v1.json")
        {
            var originalBody = context.Response.Body;
            using var memory = new MemoryStream();
            context.Response.Body = memory;

            await next(context);

            if (
                context.Response is { StatusCode: 200 }
                && MediaTypeHeaderValue.TryParse(
                    context.Response.Headers.ContentType.ToString(),
                    out var contentType
                )
                && contentType.MediaType == "application/json"
            )
            {
                memory.Position = 0;
                UpdateOpenApiV1Schema(memory);
                memory.Position = 0;
                context.Response.ContentLength = memory.Length;
            }

            await originalBody.WriteAsync(memory.GetBuffer().AsMemory(0, (int)memory.Length));
            context.Response.Body = originalBody;
        }
        else
        {
            await next(context);
        }
    }

    private static void UpdateOpenApiV1Schema(MemoryStream stream)
    {
        var jsonNode = JsonNode.Parse(stream);

        if (jsonNode is not null)
        {
            var resourcesSchema = jsonNode["components"]
                ?["schemas"]
                ?["Nav"]
                ?["properties"]
                ?["children"];
            if (resourcesSchema is not null)
            {
                resourcesSchema["items"] = new JsonObject
                {
                    ["$ref"] = "#/components/schemas/Nav",
                };

                stream.Position = 0;
                stream.SetLength(0);
                JsonSerializer.Serialize(
                    stream,
                    jsonNode,
                    new JsonSerializerOptions
                    {
                        WriteIndented = true,
                        Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping, // Use with caution
                    }
                );
            }
        }
    }
}

It could be parameterized if more than one case is found in your API.

[captainsafia]

Fixed in .NET 10.

#:sdk Microsoft.NET.Sdk.Web
#:property TargetFramework=net10.0
#:property PublishAoT=false
#:package Microsoft.AspNetCore.OpenApi@10.0.0-preview.7.*

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapControllers();

app.Run();

public class Level1
{
    public IReadOnlyList<Level1> Level1s { get; set; } = [];
}

[ApiController]
[Route("[controller]")]
public class LevelController : ControllerBase
{
    [HttpGet(Name = "GetLevels")]
    public IReadOnlyList<Level1> GetLevels()
    {
        return [];
    }

    [HttpGet("l2", Name = "GetLevels2")]
    public Level1 GetLevels2()
    {
        return new();
    }
}

{
  "openapi": "3.1.1",
  "info": {
    "title": "61424 | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:5000/"
    }
  ],
  "paths": {
    "/Level": {
      "get": {
        "tags": [
          "Level"
        ],
        "operationId": "GetLevels",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Level1"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Level1"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Level1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/Level/l2": {
      "get": {
        "tags": [
          "Level"
        ],
        "operationId": "GetLevels2",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/Level1"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Level1"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/Level1"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Level1": {
        "type": "object",
        "properties": {
          "level1s": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Level1"
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Level"
    }
  ]
}