How can I configure Microsoft.AspNetCore.OpenAPI to output direct schema $refs?

You’ll need to correct the generated document after the built‐in schema generation because the package reuses the schema reference for the first property. In other words, there isn’t currently an out‑of‑the‑box option to “tell” OpenApi to output a reference directly to the type (i.e. "#/components/schemas/TypeA") rather than “aliasing” the property (i.e. "#/components/schemas/#/properties/Completes/items"). The recommended approach is to register a document transformer (or document filter) that post‑processes the produced OpenAPI document and replaces the offending $ref values.

For example, you can implement an IDocumentFilter that walks through your components and fixes any reference that starts with the property‑shaped path:

CSHARPCopied
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class FixSchemaRefDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var schema in swaggerDoc.Components.Schemas)
        {
            FixSchemaRef(schema.Value, swaggerDoc);
        }
    }

    private void FixSchemaRef(OpenApiSchema schema, OpenApiDocument doc)
    {
        if (schema == null)
            return;

        // Fix any $ref inside the current schema's "items"
        if (schema.Items != null && 
            !string.IsNullOrEmpty(schema.Items.Reference?.ReferenceV3))
        {
            var r = schema.Items.Reference.ReferenceV3;
            if (r.StartsWith("#/components/schemas/#/properties/", StringComparison.OrdinalIgnoreCase))
            {
                // get the type name for the property (in your case, TypeA)
                // The ref is expected to be like "#/components/schemas/#/properties/Completes/items"
                // You want to change it to "#/components/schemas/TypeA"
                // Adjust the extraction based on your naming conventions.
                string typeName = "TypeA"; // for more dynamic approaches, you can extract from the original or map accordingly.
                schema.Items.Reference = new OpenApiReference
                {
                    Type = ReferenceType.Schema,
                    Id = typeName
                };
            }
        }

        // Recursively fix nested schemas.
        if (schema.Properties != null)
        {
            foreach (var prop in schema.Properties.Values)
            {
                FixSchemaRef(prop, doc);
            }
        }
        if (schema.AllOf != null)
        {
            foreach (var sub in schema.AllOf)
            {
                FixSchemaRef(sub, doc);
            }
        }
        if (schema.AnyOf != null)
        {
            foreach (var sub in schema.AnyOf)
            {
                FixSchemaRef(sub, doc);
            }
        }
        if (schema.OneOf != null)
        {
            foreach (var sub in schema.OneOf)
            {
                FixSchemaRef(sub, doc);
            }
        }
    }
}

Then, register this filter in your Startup (or wherever you configure your OpenAPI middleware):

CSHARPCopied
services.AddOpenApi(options =>
{
    // Your existing configuration, for example:
    options.DocumentName = "v1";
    options.Transformers.Add(new FixSchemaRefDocumentFilter());
});

This document filter will adjust the generated reference paths so that both the "Completes" and "Incompletes" properties will use the proper reference:

JSONCopied
"items": {
  "$ref": "#/components/schemas/TypeA"
}

Because the package currently generates a $ref that points to a property path (which isn’t valid for your gateway tools), this custom post‑processing is the way to “remap” the reference.

This approach ensures that you can tweak the output without having to modify the underlying schema generation logic in Microsoft.AspNetCore.OpenApi.