Add support for CreateSchemaReferenceId option

src/OpenApi/src/Extensions/JsonNodeSchemaExtensions.cs

@@ -168,7 +168,8 @@ internal static void ApplyDefaultValue(this JsonNode schema, object? defaultValu
     /// </remarks>
     /// <param name="schema">The <see cref="JsonNode"/> produced by the underlying schema generator.</param>
     /// <param name="context">The <see cref="JsonSchemaExporterContext"/> associated with the <see paramref="schema"/>.</param>
-    internal static void ApplyPrimitiveTypesAndFormats(this JsonNode schema, JsonSchemaExporterContext context)
+    /// <param name="createSchemaReferenceId">A delegate that generates the reference ID to create for a type.</param>
+    internal static void ApplyPrimitiveTypesAndFormats(this JsonNode schema, JsonSchemaExporterContext context, Func<JsonTypeInfo, string?> createSchemaReferenceId)
     {
         var type = context.TypeInfo.Type;
         var underlyingType = Nullable.GetUnderlyingType(type);
@@ -177,7 +178,7 @@ internal static void ApplyPrimitiveTypesAndFormats(this JsonNode schema, JsonSch
             schema[OpenApiSchemaKeywords.NullableKeyword] = openApiSchema.Nullable || (schema[OpenApiSchemaKeywords.TypeKeyword] is JsonArray schemaType && schemaType.GetValues<string>().Contains("null"));
             schema[OpenApiSchemaKeywords.TypeKeyword] = openApiSchema.Type;
             schema[OpenApiSchemaKeywords.FormatKeyword] = openApiSchema.Format;
-            schema[OpenApiConstants.SchemaId] = context.TypeInfo.GetSchemaReferenceId();
+            schema[OpenApiConstants.SchemaId] = createSchemaReferenceId(context.TypeInfo);
             schema[OpenApiSchemaKeywords.NullableKeyword] = underlyingType != null;
             // Clear out patterns that the underlying JSON schema generator uses to represent
             // validations for DateTime, DateTimeOffset, and integers.
@@ -323,7 +324,8 @@ internal static void ApplyParameterInfo(this JsonNode schema, ApiParameterDescri
     /// </summary>
     /// <param name="schema">The <see cref="JsonNode"/> produced by the underlying schema generator.</param>
     /// <param name="context">The <see cref="JsonSchemaExporterContext"/> associated with the current type.</param>
-    internal static void ApplyPolymorphismOptions(this JsonNode schema, JsonSchemaExporterContext context)
+    /// <param name="createSchemaReferenceId">A delegate that generates the reference ID to create for a type.</param>
+    internal static void ApplyPolymorphismOptions(this JsonNode schema, JsonSchemaExporterContext context, Func<JsonTypeInfo, string?> createSchemaReferenceId)
     {
         // The `context.Path.Length == 0` check is used to ensure that we only apply the polymorphism options
         // to the top-level schema and not to any nested schemas that are generated.
@@ -340,7 +342,7 @@ internal static void ApplyPolymorphismOptions(this JsonNode schema, JsonSchemaEx
                     // that we hardcode here. We could use `OpenApiReference` to construct the reference and
                     // serialize it but we use a hardcoded string here to avoid allocating a new object and
                     // working around Microsoft.OpenApi's serialization libraries.
-                    mappings[$"{discriminator}"] = $"#/components/schemas/{context.TypeInfo.GetSchemaReferenceId()}{jsonDerivedType.GetSchemaReferenceId()}";
+                    mappings[$"{discriminator}"] = $"#/components/schemas/{createSchemaReferenceId(context.TypeInfo)}{createSchemaReferenceId(jsonDerivedType)}";
                 }
             }
             schema[OpenApiSchemaKeywords.DiscriminatorKeyword] = polymorphismOptions.TypeDiscriminatorPropertyName;
@@ -353,9 +355,10 @@ internal static void ApplyPolymorphismOptions(this JsonNode schema, JsonSchemaEx
     /// </summary>
     /// <param name="schema">The <see cref="JsonNode"/> produced by the underlying schema generator.</param>
     /// <param name="context">The <see cref="JsonSchemaExporterContext"/> associated with the current type.</param>
-    internal static void ApplySchemaReferenceId(this JsonNode schema, JsonSchemaExporterContext context)
+    /// <param name="createSchemaReferenceId">A delegate that generates the reference ID to create for a type.</param>
+    internal static void ApplySchemaReferenceId(this JsonNode schema, JsonSchemaExporterContext context, Func<JsonTypeInfo, string?> createSchemaReferenceId)
     {
-        if (context.TypeInfo.GetSchemaReferenceId() is { } schemaReferenceId)
+        if (createSchemaReferenceId(context.TypeInfo) is { } schemaReferenceId)
         {
             schema[OpenApiConstants.SchemaId] = schemaReferenceId;
         }

src/OpenApi/src/PublicAPI.Unshipped.txt

@@ -4,6 +4,8 @@ Microsoft.AspNetCore.OpenApi.IOpenApiDocumentTransformer.TransformAsync(Microsof
 Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext.Description.get -> Microsoft.AspNetCore.Mvc.ApiExplorer.ApiDescription!
 Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext.Description.init -> void
 Microsoft.AspNetCore.OpenApi.OpenApiOptions
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.CreateSchemaReferenceId.get -> System.Func<System.Text.Json.Serialization.Metadata.JsonTypeInfo!, string?>!
+Microsoft.AspNetCore.OpenApi.OpenApiOptions.CreateSchemaReferenceId.set -> void
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.DocumentName.get -> string!
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.OpenApiOptions() -> void
 Microsoft.AspNetCore.OpenApi.OpenApiOptions.OpenApiVersion.get -> Microsoft.OpenApi.OpenApiSpecVersion
@@ -27,6 +29,7 @@ Microsoft.AspNetCore.OpenApi.OpenApiSchemaTransformerContext.Type.get -> System.
 Microsoft.AspNetCore.OpenApi.OpenApiSchemaTransformerContext.Type.init -> void
 Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions
 static Microsoft.AspNetCore.Builder.OpenApiEndpointRouteBuilderExtensions.MapOpenApi(this Microsoft.AspNetCore.Routing.IEndpointRouteBuilder! endpoints, string! pattern = "/openapi/{documentName}.json") -> Microsoft.AspNetCore.Builder.IEndpointConventionBuilder!
+static Microsoft.AspNetCore.OpenApi.OpenApiOptions.CreateDefaultSchemaReferenceId(System.Text.Json.Serialization.Metadata.JsonTypeInfo! jsonTypeInfo) -> string?
 static Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
 static Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, string! documentName) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
 static Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, string! documentName, System.Action<Microsoft.AspNetCore.OpenApi.OpenApiOptions!>! configureOptions) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!

src/OpenApi/src/Services/OpenApiOptions.cs

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization.Metadata;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.OpenApi;
 using Microsoft.OpenApi.Models;
@@ -16,6 +17,13 @@ public sealed class OpenApiOptions
     internal readonly List<IOpenApiDocumentTransformer> DocumentTransformers = [];
     internal readonly List<Func<OpenApiSchema, OpenApiSchemaTransformerContext, CancellationToken, Task>> SchemaTransformers = [];
 
+    /// <summary>
+    /// A default implementation for creating a schema reference ID for a given <see cref="JsonTypeInfo"/>.
+    /// </summary>
+    /// <param name="jsonTypeInfo">The <see cref="JsonTypeInfo"/> associated with the schema we are generating a reference ID for.</param>
+    /// <returns>The reference ID to use for the schema or <c>null</c>  if the schema should always be inlined.</returns>
+    public static string? CreateDefaultSchemaReferenceId(JsonTypeInfo jsonTypeInfo) => jsonTypeInfo.GetSchemaReferenceId();
+
     /// <summary>
     /// Initializes a new instance of the <see cref="OpenApiOptions"/> class
     /// with the default <see cref="ShouldInclude"/> predicate.
@@ -40,6 +48,15 @@ public OpenApiOptions()
     /// </summary>
     public Func<ApiDescription, bool> ShouldInclude { get; set; }
 
+    /// <summary>
+    /// A delegate to determine how reference IDs should be created for schemas associated with types in the given OpenAPI document.
+    /// </summary>
+    /// <remarks>
+    /// The default implementation uses the <see cref="CreateDefaultSchemaReferenceId"/> method to generate reference IDs. When
+    /// the provided delegate returns <c>null</c>, the schema associated with the <see cref="JsonTypeInfo"/>  will always be inlined.
+    /// </remarks>
+    public Func<JsonTypeInfo, string?> CreateSchemaReferenceId { get; set; } = CreateDefaultSchemaReferenceId;
+
     /// <summary>
     /// Registers a new document transformer on the current <see cref="OpenApiOptions"/> instance.
     /// </summary>

src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs

@@ -88,9 +88,10 @@ internal sealed class OpenApiSchemaService(
             {
                 schema = new JsonObject();
             }
-            schema.ApplyPrimitiveTypesAndFormats(context);
-            schema.ApplySchemaReferenceId(context);
-            schema.ApplyPolymorphismOptions(context);
+            var createSchemaReferenceId = optionsMonitor.Get(documentName).CreateSchemaReferenceId;
+            schema.ApplyPrimitiveTypesAndFormats(context, createSchemaReferenceId);
+            schema.ApplySchemaReferenceId(context, createSchemaReferenceId);
+            schema.ApplyPolymorphismOptions(context, createSchemaReferenceId);
             if (context.PropertyInfo is { } jsonPropertyInfo)
             {
                 // Short-circuit STJ's handling of nested properties, which uses a reference to the

src/OpenApi/test/Services/CreateSchemaReferenceIdTests.cs

@@ -0,0 +1,201 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Text.Json.Serialization.Metadata;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi.Any;
+using Microsoft.OpenApi.Models;
+
+public class CreateSchemaReferenceIdTests : OpenApiDocumentServiceTestBase
+{
+    [Fact]
+    public async Task HandlesPolymorphicTypeWithCustomReferenceIds()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapPost("/api", (Shape shape) => { });
+        string createReferenceId(JsonTypeInfo jsonTypeInfo)
+        {
+            return jsonTypeInfo.Type.Name switch
+            {
+                "Shape" => "MyShape",
+                "Triangle" => "MyTriangle",
+                "Square" => "MySquare",
+                _ => jsonTypeInfo.Type.Name,
+            };
+        }
+        var options = new OpenApiOptions { CreateSchemaReferenceId = createReferenceId };
+
+        // Assert
+        await VerifyOpenApiDocument(builder, options, document =>
+        {
+            var operation = document.Paths["/api"].Operations[OperationType.Post];
+            Assert.NotNull(operation.RequestBody);
+            var requestBody = operation.RequestBody.Content;
+            Assert.True(requestBody.TryGetValue("application/json", out var mediaType));
+            var schema = mediaType.Schema.GetEffective(document);
+            // Assert discriminator mappings have been configured correctly
+            Assert.Equal("$type", schema.Discriminator.PropertyName);
+            Assert.Contains(schema.Discriminator.PropertyName, schema.Required);
+            Assert.Collection(schema.Discriminator.Mapping,
+                item => Assert.Equal("triangle", item.Key),
+                item => Assert.Equal("square", item.Key)
+            );
+            Assert.Collection(schema.Discriminator.Mapping,
+                item => Assert.Equal("#/components/schemas/MyShapeMyTriangle", item.Value),
+                item => Assert.Equal("#/components/schemas/MyShapeMySquare", item.Value)
+            );
+            // Assert the schemas with the discriminator have been inserted into the components
+            Assert.True(document.Components.Schemas.TryGetValue("MyShapeMyTriangle", out var triangleSchema));
+            Assert.Contains(schema.Discriminator.PropertyName, triangleSchema.Properties.Keys);
+            Assert.Equal("triangle", ((OpenApiString)triangleSchema.Properties[schema.Discriminator.PropertyName].Enum.First()).Value);
+            Assert.True(document.Components.Schemas.TryGetValue("MyShapeMySquare", out var squareSchema));
+            Assert.Equal("square", ((OpenApiString)squareSchema.Properties[schema.Discriminator.PropertyName].Enum.First()).Value);
+        });
+    }
+
+    [Fact]
+    public async Task GeneratesSchemaForPoco_WithSchemaReferenceIdCustomization()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapPost("/", (Todo todo) => { });
+        var options = new OpenApiOptions { CreateSchemaReferenceId = (type) => $"{type.Type.Name}Schema" };
+
+        // Assert
+        await VerifyOpenApiDocument(builder, options, document =>
+        {
+            var operation = document.Paths["/"].Operations[OperationType.Post];
+            var requestBody = operation.RequestBody;
+
+            Assert.NotNull(requestBody);
+            var content = Assert.Single(requestBody.Content);
+            Assert.Equal("application/json", content.Key);
+            Assert.NotNull(content.Value.Schema);
+            Assert.Equal("TodoSchema", content.Value.Schema.Reference.Id);
+            var schema = content.Value.Schema.GetEffective(document);
+            Assert.Equal("object", schema.Type);
+            Assert.Collection(schema.Properties,
+                property =>
+                {
+                    Assert.Equal("id", property.Key);
+                    Assert.Equal("integer", property.Value.Type);
+                },
+                property =>
+                {
+                    Assert.Equal("title", property.Key);
+                    Assert.Equal("string", property.Value.Type);
+                },
+                property =>
+                {
+                    Assert.Equal("completed", property.Key);
+                    Assert.Equal("boolean", property.Value.Type);
+                },
+                property =>
+                {
+                    Assert.Equal("createdAt", property.Key);
+                    Assert.Equal("string", property.Value.Type);
+                    Assert.Equal("date-time", property.Value.Format);
+                });
+
+        });
+    }
+
+    [Fact]
+    public async Task GeneratesInlineSchemaForPoco_WithCustomNullId()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+        builder.MapPost("/", (Todo todo) => { });
+        var options = new OpenApiOptions { CreateSchemaReferenceId = (type) => type.Type.Name == "Todo" ? null : $"{type.Type.Name}Schema" };
+
+        // Assert
+        await VerifyOpenApiDocument(builder, options, document =>
+        {
+            var operation = document.Paths["/"].Operations[OperationType.Post];
+            var requestBody = operation.RequestBody;
+
+            Assert.NotNull(requestBody);
+            var content = Assert.Single(requestBody.Content);
+            Assert.Equal("application/json", content.Key);
+            Assert.NotNull(content.Value.Schema);
+            // Assert that no reference was created and the schema is inlined
+            var schema = content.Value.Schema;
+            Assert.Null(schema.Reference);
+            Assert.Equal("object", schema.Type);
+            Assert.Collection(schema.Properties,
+                property =>
+                {
+                    Assert.Equal("id", property.Key);
+                    Assert.Equal("integer", property.Value.Type);
+                },
+                property =>
+                {
+                    Assert.Equal("title", property.Key);
+                    Assert.Equal("string", property.Value.Type);
+                },
+                property =>
+                {
+                    Assert.Equal("completed", property.Key);
+                    Assert.Equal("boolean", property.Value.Type);
+                },
+                property =>
+                {
+                    Assert.Equal("createdAt", property.Key);
+                    Assert.Equal("string", property.Value.Type);
+                    Assert.Equal("date-time", property.Value.Format);
+                });
+
+        });
+    }
+
+    [Fact]
+    public async Task CanCallDefaultImplementationFromCustomOne()
+    {
+        var builder = CreateBuilder();
+
+        builder.MapPost("/", (Todo todo) => new TodoWithDueDate(todo.Id, todo.Title, todo.Completed, todo.CreatedAt, DateTime.UtcNow));
+        var options = new OpenApiOptions
+        {
+            CreateSchemaReferenceId = (type) =>
+            {
+                if (type.Type.Name == "Todo")
+                {
+                    return null;
+                }
+                return OpenApiOptions.CreateDefaultSchemaReferenceId(type);
+            }
+        };
+
+        await VerifyOpenApiDocument(builder, options, document =>
+        {
+            var operation = document.Paths["/"].Operations[OperationType.Post];
+            var requestBody = operation.RequestBody;
+            var response = operation.Responses["200"];
+
+            // Assert that no reference was created for the Todo type
+            Assert.NotNull(requestBody);
+            var content = Assert.Single(requestBody.Content);
+            Assert.Equal("application/json", content.Key);
+            Assert.NotNull(content.Value.Schema);
+            var schema = content.Value.Schema;
+            Assert.Null(schema.Reference);
+
+            // Assert that a reference was created for the TodoWithDueDate type
+            Assert.NotNull(response);
+            var responseContent = Assert.Single(response.Content);
+            Assert.Equal("application/json", responseContent.Key);
+            Assert.NotNull(responseContent.Value.Schema);
+            var responseSchema = responseContent.Value.Schema;
+            Assert.NotNull(responseSchema.Reference);
+            Assert.Equal("TodoWithDueDate", responseSchema.Reference.Id);
+        });
+    }
+}