Custom CreateSchemaReferenceId not always used in OpenAPI schema $ref

[davidkarlsson]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

If you set a custom OpenApiOptions.CreateSchemaReferenceId delegate it won't use the custom id from it when setting the $ref for a property that has the same type as its declaring type. The reason for this seems to be this code in OpenApiSchemaService where it uses the default JsonTypeInfo.GetSchemaReferenceId extension method instead of the one from settings:

if (jsonPropertyInfo.PropertyType == jsonPropertyInfo.DeclaringType)
{
    return new JsonObject { [OpenApiSchemaKeywords.RefKeyword] = context.TypeInfo.GetSchemaReferenceId() };
}

Expected Behavior

I expected the custom CreateSchemaReferenceId to be used even for nested properties of the same type as its parent which doesn't seem to be the case as far as I can tell.

Steps To Reproduce

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi(options =>
{
    options.CreateSchemaReferenceId = _ => "Overridden";
});

builder.Services.AddControllersWithViews();

var app = builder.Build();

app.UseRouting();

app.UseAuthorization();

app.MapOpenApi();

app.MapControllers();

app.Run();

[ApiController]
[Route("Api/[controller]")]
public class TestController : ControllerBase
{
    [HttpGet("")]
    [ProducesResponseType<Parent>(StatusCodes.Status200OK)]
    public Ok<Parent> Index()
    {
        return TypedResults.Ok(new Parent { RequiredChild = new() });
    }
}

public class Parent
{
    public Child? NullableChild { get; init; }
    public required Child RequiredChild { get; init; }

    public Parent? NestedParent { get; set; }
}

public class Child;

/openapi/v1.json:

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenApiTest | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://localhost:5001"
    }
  ],
  "paths": {
    "/Api/Test": {
      "get": {
        "tags": [
          "Test"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/Overridden"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Overridden"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/Overridden"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Overridden": {
        "required": [
          "requiredChild"
        ],
        "type": "object",
        "properties": {
          "nullableChild": {
            "$ref": "#/components/schemas/Overridden2"
          },
          "requiredChild": {
            "$ref": "#/components/schemas/Overridden3"
          },
          "nestedParent": {
            "$ref": "#/components/schemas/Parent"
          }
        }
      },
      "Overridden2": {
        "type": "object",
        "nullable": true
      },
      "Overridden3": {
        "type": "object"
      }
    }
  },
  "tags": [
    {
      "name": "Test"
    }
  ]
}

Here I expected the nestedParent $ref to be #/components/schemas/Overridden and not #/components/schemas/Parent since that's what it will reference if you don't override OpenApiOptions.CreateSchemaReferenceId.

Exceptions (if any)

No response

.NET Version

9.0.100-rc.1.24452.12

Anything else?

No response

[marthijn]

Same problem here I think. When I use types as follows:

public class ModelA { .. }
public class ModelB
{
  public ModelA? MyModelA { get; set; }
}

[ProducesResponseType(typeof(ModelA), StatusCodes.Status200OK)]
public IActionResult Function1(){ .. }

[ProducesResponseType(typeof(ModelB), StatusCodes.Status200OK)]
public IActionResult Function2(){ .. }

The OpenAPI spec will become something like this

"ModelA": {
  ...
  "nullable": true
},
"ModelA2": {
},

The difference is the "nullable": true property (as used in class ModelB). In my opinion this should not result in a duplicate.

Also, when ModelA is used in a list:

public class ModelC
{
  public List<ModelA> Models { get; set; }
}

a version 3 is created:

"ModelA3": {
},

"List`1": {
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/ModelA3"
  }
},

[davidkarlsson]

@marthijn That's not what this issue is about though if I understand you correctly. This issue is about that the custom delegate you set with OpenApiOptions.CreateSchemaReferenceId isn't being used to generate schema reference ids in a certain case.

I admit that my repro isn't very clear about this though because I was experimenting with the nullability stuff you are referencing as well when I was testing this.

I'm not sure but your issue sounds more like it's about a shortcoming with the OpenAPI 3.0 spec regarding nullability which #58619 would fix I think?

[marthijn]

@davidkarlsson thanks for the clarification, I indeed misunderstood your issue!

[captainsafia]

Original issue is 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;
using Microsoft.AspNetCore.Http.HttpResults;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi(options =>
{
    options.CreateSchemaReferenceId = _ => "Overridden";
});

builder.Services.AddControllersWithViews();

var app = builder.Build();

app.UseRouting();

app.UseAuthorization();

app.MapOpenApi();

app.MapControllers();

app.Run();

[ApiController]
[Route("Api/[controller]")]
public class TestController : ControllerBase
{
    [HttpGet("")]
    [ProducesResponseType<Parent>(StatusCodes.Status200OK)]
    public Ok<Parent> Index()
    {
        return TypedResults.Ok(new Parent { RequiredChild = new() });
    }
}

public class Parent
{
    public Child? NullableChild { get; init; }
    public required Child RequiredChild { get; init; }

    public Parent? NestedParent { get; set; }
}

public class Child;

{
  "openapi": "3.1.1",
  "info": {
    "title": "61527 | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:5000/"
    }
  ],
  "paths": {
    "/Api/Test": {
      "get": {
        "tags": [
          "Test"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/Overridden"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Overridden"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/Overridden"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Overridden": {
        "required": [
          "requiredChild"
        ],
        "type": "object",
        "properties": {
          "nullableChild": {
            "$ref": "#/components/schemas/Overridden"
          },
          "requiredChild": {
            "$ref": "#/components/schemas/Overridden"
          },
          "nestedParent": {
            "$ref": "#/components/schemas/Overridden"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Test"
    }
  ]
}