Fix openapi schema xml comments handling for referenced schemas (#62213)

* Update OpenAPI range formatting to format using the target culture and Update tests to write in the InvariantCulture

* Updated schema reference XML Comment handling.

Update handling of nested schemas and referenced schemas

* Only set a schema property description when it's not a schema reference

Update XmlCommentGenerator.Emitter.cs to skip applying property descriptions when it's a schema reference.

Schema transformers get the full schema and not the schema reference. So when the description is updated it would update it for all locations.

* Snapshot the generated openapi as part of the OpenApi source generator tests

* Uncomment and remove commented code

* Rename emitted variable to isInlinedSchema

* Add handling of XML Comments on properties with a schema reference with Metadata properties

* Improve XmlComments SchemaReference tests and revert modified unrelated tests

* Revert outputting OpenApi.json snapshots in the XmlSourceGenerator Tests

* Fix dereference null warning because the compiler cannot analyze it from a boolean value

* Fix null assignment warning

* Add tests around <example> comments

* Fix formatting of emitted code

* Revert change to OpenApiSchemaService

Author: desjoerd

src/OpenApi/gen/XmlCommentGenerator.Emitter.cs

@@ -449,17 +449,7 @@ private static OpenApiParameter UnwrapOpenApiParameter(IOpenApiParameter sourceP
     {
         public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)
         {
-            if (context.JsonPropertyInfo is { AttributeProvider: PropertyInfo propertyInfo })
-            {
-                if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment))
-                {
-                    schema.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
-                    if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
-                    {
-                        schema.Example = jsonString.Parse();
-                    }
-                }
-            }
+            // Apply comments from the type
             if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(context.JsonTypeInfo.Type.CreateDocumentationId()), out var typeComment))
             {
                 schema.Description = typeComment.Summary;
@@ -468,6 +458,34 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext
                     schema.Example = jsonString.Parse();
                 }
             }
+
+            if (context.JsonPropertyInfo is { AttributeProvider: PropertyInfo propertyInfo })
+            {
+                // Apply comments from the property
+                if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment))
+                {
+                    if (schema.Metadata is null
+                        || !schema.Metadata.TryGetValue("x-schema-id", out var schemaId)
+                        || string.IsNullOrEmpty(schemaId as string))
+                    {
+                        // Inlined schema
+                        schema.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!;
+                        if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
+                        {
+                            schema.Example = jsonString.Parse();
+                        }
+                    }
+                    else
+                    {
+                        // Schema Reference
+                        schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!;
+                        if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
+                        {
+                            schema.Metadata["x-ref-example"] = jsonString.Parse()!;
+                        }
+                    }
+                }
+            }
             return Task.CompletedTask;
         }
     }
@@ -507,6 +525,7 @@ file static class GeneratedServiceCollectionExtensions
 {{GenerateAddOpenApiInterceptions(groupedAddOpenApiInvocations)}}
     }
 }
+
 """;
 
     internal static string GetAddOpenApiInterceptor(AddOpenApiOverloadVariant overloadVariant) => overloadVariant switch

src/OpenApi/src/Extensions/OpenApiDocumentExtensions.cs

@@ -1,6 +1,8 @@
 // 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.Nodes;
+
 namespace Microsoft.AspNetCore.OpenApi;
 
 internal static class OpenApiDocumentExtensions
@@ -21,6 +23,19 @@ public static IOpenApiSchema AddOpenApiSchemaByReference(this OpenApiDocument do
         document.Workspace ??= new();
         var location = document.BaseUri + "/components/schemas/" + schemaId;
         document.Workspace.RegisterComponentForDocument(document, schema, location);
-        return new OpenApiSchemaReference(schemaId, document);
+
+        object? description = null;
+        object? example = null;
+        if (schema is OpenApiSchema actualSchema)
+        {
+            actualSchema.Metadata?.TryGetValue(OpenApiConstants.RefDescriptionAnnotation, out description);
+            actualSchema.Metadata?.TryGetValue(OpenApiConstants.RefExampleAnnotation, out example);
+        }
+
+        return new OpenApiSchemaReference(schemaId, document)
+        {
+            Description = description as string,
+            Examples = example is JsonNode exampleJson ? [exampleJson] : null,
+        };
     }
 }

src/OpenApi/src/Services/OpenApiConstants.cs

@@ -13,6 +13,8 @@ internal static class OpenApiConstants
     internal const string DescriptionId = "x-aspnetcore-id";
     internal const string SchemaId = "x-schema-id";
     internal const string RefId = "x-ref-id";
+    internal const string RefDescriptionAnnotation = "x-ref-description";
+    internal const string RefExampleAnnotation = "x-ref-example";
     internal const string DefaultOpenApiResponseKey = "default";
     // Since there's a finite set of HTTP methods that can be included in a given
     // OpenApiPaths, we can pre-allocate an array of these methods and use a direct

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs

@@ -1,4 +1,4 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Net.Http;
@@ -175,6 +175,7 @@ internal class User : IUser
     /// <inheritdoc/>
     public string Name { get; set; }
 }
+
 """;
         var generator = new XmlCommentGenerator();
         await SnapshotTestHelper.Verify(source, generator, out var compilation);
@@ -260,4 +261,161 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document =>
             Assert.Equal("The user's display name.", user.Properties["name"].Description);
         });
     }
+
+    [Fact]
+    public async Task XmlCommentsOnPropertiesShouldApplyToSchemaReferences()
+    {
+        var source = """
+using System;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.DependencyInjection;
+
+var builder = WebApplication.CreateBuilder();
+
+builder.Services.AddOpenApi(options => {
+    var prevCreateSchemaReferenceId = options.CreateSchemaReferenceId;
+    options.CreateSchemaReferenceId = (x) => x.Type == typeof(ModelInline) ? null : prevCreateSchemaReferenceId(x);
+});
+
+var app = builder.Build();
+
+app.MapPost("/example", (RootModel model) => { });
+
+app.Run();
+
+/// <summary>
+/// Comment on class ModelWithSummary.
+/// </summary>
+/// <example>
+/// { "street": "ModelWithSummaryClass" }
+/// </example>
+public class ModelWithSummary
+{
+    public string Street { get; set; }
+}
+
+public class ModelWithoutSummary
+{
+    public string Street { get; set; }
+}
+
+/// <summary>
+/// Comment on class ModelInline.
+/// </summary>
+/// <example>
+/// { "street": "ModelInlineClass" }
+/// </example>
+public class ModelInline
+{
+    public string Street { get; set; }
+}
+
+/// <summary>
+/// Comment on class RootModel.
+/// </summary>
+/// <example>
+/// { }
+/// </example>
+public class RootModel
+{
+    public ModelWithSummary NoPropertyComment { get; set; }
+
+    /// <summary>
+    /// Comment on property ModelWithSummary1.
+    /// </summary>
+    /// <example>
+    /// { "street": "ModelWithSummary1Prop" }
+    /// </example>
+    public ModelWithSummary ModelWithSummary1 { get; set; }
+
+    /// <summary>
+    /// Comment on property ModelWithSummary2.
+    /// </summary>
+    /// <example>
+    /// { "street": "ModelWithSummary2Prop" }
+    /// </example>
+    public ModelWithSummary ModelWithSummary2 { get; set; }
+
+    /// <summary>
+    /// Comment on property ModelWithoutSummary1.
+    /// </summary>
+    /// <example>
+    /// { "street": "ModelWithoutSummary1Prop" }
+    /// </example>
+    public ModelWithoutSummary ModelWithoutSummary1 { get; set; }
+
+    /// <summary>
+    /// Comment on property ModelWithoutSummary2.
+    /// </summary>
+    /// <example>
+    /// { "street": "ModelWithoutSummary2Prop" }
+    /// </example>
+    public ModelWithoutSummary ModelWithoutSummary2 { get; set; }
+
+    /// <summary>
+    /// Comment on property ModelInline1.
+    /// </summary>
+    /// <example>
+    /// { "street": "ModelInline1Prop" }
+    /// </example>
+    public ModelInline ModelInline1 { get; set; }
+
+    /// <summary>
+    /// Comment on property ModelInline2.
+    /// </summary>
+    /// <example>
+    /// { "street": "ModelInline2Prop" }
+    /// </example>
+    public ModelInline ModelInline2 { get; set; }
+}
+""";
+        var generator = new XmlCommentGenerator();
+        await SnapshotTestHelper.Verify(source, generator, out var compilation);
+        await SnapshotTestHelper.VerifyOpenApi(compilation, document =>
+        {
+            var path = document.Paths["/example"].Operations[HttpMethod.Post];
+            var exampleOperationBodySchema = path.RequestBody.Content["application/json"].Schema;
+            Assert.Equal("Comment on class RootModel.", exampleOperationBodySchema.Description);
+
+            var rootModelSchema = document.Components.Schemas["RootModel"];
+            Assert.Equal("Comment on class RootModel.", rootModelSchema.Description);
+
+            var modelWithSummary = document.Components.Schemas["ModelWithSummary"];
+            Assert.Equal("Comment on class ModelWithSummary.", modelWithSummary.Description);
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse("""{ "street": "ModelWithSummaryClass" }"""), modelWithSummary.Example));
+
+            var modelWithoutSummary = document.Components.Schemas["ModelWithoutSummary"];
+            Assert.Null(modelWithoutSummary.Description);
+
+            Assert.DoesNotContain("ModelInline", document.Components.Schemas.Keys);
+
+            // Check RootModel properties
+            var noPropertyCommentProp = Assert.IsType<OpenApiSchemaReference>(rootModelSchema.Properties["noPropertyComment"]);
+            Assert.Null(noPropertyCommentProp.Reference.Description);
+
+            var modelWithSummary1Prop = Assert.IsType<OpenApiSchemaReference>(rootModelSchema.Properties["modelWithSummary1"]);
+            Assert.Equal("Comment on property ModelWithSummary1.", modelWithSummary1Prop.Description);
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse("""{ "street": "ModelWithSummary1Prop" }"""), modelWithSummary1Prop.Examples[0]));
+
+            var modelWithSummary2Prop = Assert.IsType<OpenApiSchemaReference>(rootModelSchema.Properties["modelWithSummary2"]);
+            Assert.Equal("Comment on property ModelWithSummary2.", modelWithSummary2Prop.Description);
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse("""{ "street": "ModelWithSummary2Prop" }"""), modelWithSummary2Prop.Examples[0]));
+
+            var modelWithoutSummary1Prop = Assert.IsType<OpenApiSchemaReference>(rootModelSchema.Properties["modelWithoutSummary1"]);
+            Assert.Equal("Comment on property ModelWithoutSummary1.", modelWithoutSummary1Prop.Description);
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse("""{ "street": "ModelWithoutSummary1Prop" }"""), modelWithoutSummary1Prop.Examples[0]));
+
+            var modelWithoutSummary2Prop = Assert.IsType<OpenApiSchemaReference>(rootModelSchema.Properties["modelWithoutSummary2"]);
+            Assert.Equal("Comment on property ModelWithoutSummary2.", modelWithoutSummary2Prop.Description);
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse("""{ "street": "ModelWithoutSummary2Prop" }"""), modelWithoutSummary2Prop.Examples[0]));
+
+            var modelInline1Prop = Assert.IsType<OpenApiSchema>(rootModelSchema.Properties["modelInline1"]);
+            Assert.Equal("Comment on property ModelInline1.", modelInline1Prop.Description);
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse("""{ "street": "ModelInline1Prop" }"""), modelInline1Prop.Example));
+
+            var modelInline2Prop = Assert.IsType<OpenApiSchema>(rootModelSchema.Properties["modelInline2"]);
+            Assert.Equal("Comment on property ModelInline2.", modelInline2Prop.Description);
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse("""{ "street": "ModelInline2Prop" }"""), modelInline2Prop.Example));
+        });
+    }
 }

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs

@@ -1,4 +1,4 @@
-//HintName: OpenApiXmlCommentSupport.generated.cs
+//HintName: OpenApiXmlCommentSupport.generated.cs
 //------------------------------------------------------------------------------
 // <auto-generated>
 //     This code was generated by a tool.
@@ -431,17 +431,7 @@ private static OpenApiParameter UnwrapOpenApiParameter(IOpenApiParameter sourceP
     {
         public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)
         {
-            if (context.JsonPropertyInfo is { AttributeProvider: PropertyInfo propertyInfo })
-            {
-                if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment))
-                {
-                    schema.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
-                    if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
-                    {
-                        schema.Example = jsonString.Parse();
-                    }
-                }
-            }
+            // Apply comments from the type
             if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(context.JsonTypeInfo.Type.CreateDocumentationId()), out var typeComment))
             {
                 schema.Description = typeComment.Summary;
@@ -450,6 +440,34 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext
                     schema.Example = jsonString.Parse();
                 }
             }
+
+            if (context.JsonPropertyInfo is { AttributeProvider: PropertyInfo propertyInfo })
+            {
+                // Apply comments from the property
+                if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment))
+                {
+                    if (schema.Metadata is null
+                        || !schema.Metadata.TryGetValue("x-schema-id", out var schemaId)
+                        || string.IsNullOrEmpty(schemaId as string))
+                    {
+                        // Inlined schema
+                        schema.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!;
+                        if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
+                        {
+                            schema.Example = jsonString.Parse();
+                        }
+                    }
+                    else
+                    {
+                        // Schema Reference
+                        schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!;
+                        if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
+                        {
+                            schema.Metadata["x-ref-example"] = jsonString.Parse()!;
+                        }
+                    }
+                }
+            }
             return Task.CompletedTask;
         }
     }

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs

@@ -460,17 +460,7 @@ private static OpenApiParameter UnwrapOpenApiParameter(IOpenApiParameter sourceP
     {
         public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)
         {
-            if (context.JsonPropertyInfo is { AttributeProvider: PropertyInfo propertyInfo })
-            {
-                if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment))
-                {
-                    schema.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
-                    if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
-                    {
-                        schema.Example = jsonString.Parse();
-                    }
-                }
-            }
+            // Apply comments from the type
             if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(context.JsonTypeInfo.Type.CreateDocumentationId()), out var typeComment))
             {
                 schema.Description = typeComment.Summary;
@@ -479,6 +469,34 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext
                     schema.Example = jsonString.Parse();
                 }
             }
+
+            if (context.JsonPropertyInfo is { AttributeProvider: PropertyInfo propertyInfo })
+            {
+                // Apply comments from the property
+                if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment))
+                {
+                    if (schema.Metadata is null
+                        || !schema.Metadata.TryGetValue("x-schema-id", out var schemaId)
+                        || string.IsNullOrEmpty(schemaId as string))
+                    {
+                        // Inlined schema
+                        schema.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!;
+                        if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
+                        {
+                            schema.Example = jsonString.Parse();
+                        }
+                    }
+                    else
+                    {
+                        // Schema Reference
+                        schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!;
+                        if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
+                        {
+                            schema.Metadata["x-ref-example"] = jsonString.Parse()!;
+                        }
+                    }
+                }
+            }
             return Task.CompletedTask;
         }
     }