Add support for CreateSchemaReferenceId option (#56753)

* Add support for CreateSchemaReferenceId option

* Apply suggestions from code review

Co-authored-by: Martin Costello <martin@martincostello.com>

* Add test for reference ID de-dupe with CreateSchemaReferenceId

---------

Co-authored-by: Martin Costello <martin@martincostello.com>

Author: Safia Abdalla

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 <see langword="null"/> 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 <see langword="null"/>, 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