OpenApi: Support `UseAllOfToExtendReferenceSchemas`

[lindeberg]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

The problem is that nullable references are created like this:

"NullableOfChocolateChip": {
  "type": "integer",
  "nullable": true
}

"result": {
  "$ref": "#/components/schemas/NullableOfChocolateChip"
}

Describe the solution you'd like

I want OpenAPI references to be created using allOf so that I can make the reference nullable. For example:

"cookie": {
  "allOf": [
    {
      "$ref": "#/components/schemas/ChocolateChip"
    }
  ],
  "nullable": true
}

Additional context

With SwashBuckle, this works by:

// https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2378#issuecomment-1072977332
// https://github.com/OAI/OpenAPI-Specification/issues/1368
options.UseAllOfToExtendReferenceSchemas();
options.SupportNonNullableReferenceTypes();

[pinkfloydx33]

Something like this is one of the things keeping us from migrating off of swashbuckle. Defining top-level NullableOfXYZ schemas side-by-side with XYZ schemas is an unfortunate decision made here. While certainly allowed by OAS, I don't believe it's a requirement, otherwise nullability wouldn't be an option elsewhere in the spec. allOf [ NullableOfXYZ and { nullable=true} ] would just be ludicrous, as would anyOf [ NullableOfXyz or null ]

We would definitely appreciate the knobs to control this behavior. Without it we'd likely be far or from migrating

[jgarciadelanoceda]

It may be resolved with net10?
It adds openApi 3.1 support that's makes possible to describe the type as an array of null and the proper type.
In openApi 3.0 it was not possible if you described the type as a ref to have siblings, in openApi 3.1 this limitation does not exist as far as I know

[captainsafia]

This is fixed in .NET 10 with support for full JSON schemas in OpenAPI.NET.

#: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.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapPost("/chocolate-chip", (ChocolateChip? chip) =>
{
    if (string.IsNullOrEmpty(chip.Flavor))
    {
        return Results.ValidationProblem(new Dictionary<string, string[]>
        {
            { "Flavor", new[] { "The Flavor field is required." } }
        });
    }

    return Results.Created($"/chocolate-chip/{chip.Flavor}", chip);
});

app.Run();

public class ChocolateChip
{
    public string Flavor { get; set; }
}

{
  "openapi": "3.1.1",
  "info": {
    "title": "61632 | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:5000/"
    }
  ],
  "paths": {
    "/chocolate-chip": {
      "post": {
        "tags": [
          "61632"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChocolateChip"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ChocolateChip": {
        "type": [
          "null",
          "object"
        ],
        "properties": {
          "flavor": {
            "type": "string"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "61632"
    }
  ]
}