From 380d209844728d963dc2b561102ab9a5b10ebe79 Mon Sep 17 00:00:00 2001 From: Safia Abdalla Date: Mon, 11 Aug 2025 13:49:48 -0700 Subject: [PATCH 1/5] Standardize pattern used for property comments --- .../gen/XmlCommentGenerator.Emitter.cs | 29 ++++++++-- .../AdditionalTextsTests.Schemas.cs | 2 +- .../CompletenessTests.cs | 53 +++++++++++++++++++ .../OperationTests.MinimalApis.cs | 46 ++++++++++++++-- .../SchemaTests.cs | 6 ++- ...ApiXmlCommentSupport.generated.verified.cs | 29 ++++++++-- ...ApiXmlCommentSupport.generated.verified.cs | 29 ++++++++-- ...ApiXmlCommentSupport.generated.verified.cs | 35 ++++++++++-- ...ApiXmlCommentSupport.generated.verified.cs | 29 ++++++++-- ...ApiXmlCommentSupport.generated.verified.cs | 33 ++++++++++-- ...ApiXmlCommentSupport.generated.verified.cs | 29 ++++++++-- ...ApiXmlCommentSupport.generated.verified.cs | 29 ++++++++-- ...ApiXmlCommentSupport.generated.verified.cs | 29 ++++++++-- ...nApiDocument_documentName=xml.verified.txt | 2 +- ...nApiDocument_documentName=xml.verified.txt | 2 +- ...ifyOpenApiDocumentIsInvariant.verified.txt | 2 +- 16 files changed, 340 insertions(+), 44 deletions(-) diff --git a/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs b/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs index d83aa5028c18..b7bff6ff1282 100644 --- a/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs +++ b/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs @@ -452,11 +452,20 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyDocId), out var propertyComment)) { var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name); + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } if (parameter is null) { if (operation.RequestBody is not null) { - operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + operation.RequestBody.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { var content = operation.RequestBody.Content?.Values; @@ -476,7 +485,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var targetOperationParameter = UnwrapOpenApiParameter(parameter); if (targetOperationParameter is not null) { - targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + targetOperationParameter.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { targetOperationParameter.Example = jsonString.Parse(); @@ -533,12 +542,21 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext // Apply comments from the property if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment)) { + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } 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!; + schema.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Example = jsonString.Parse(); @@ -547,7 +565,10 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext else { // Schema Reference - schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!; + if (!string.IsNullOrEmpty(description)) + { + schema.Metadata["x-ref-description"] = description; + } if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Metadata["x-ref-example"] = jsonString.Parse()!; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs index d63d608c86a4..9c674c93c60d 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs @@ -215,7 +215,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, additionalAssemblies, docume todo = path.RequestBody.Content["application/json"].Schema; Assert.Equal("The identifier of the todo.", todo.Properties["id"].Description); Assert.Equal("The name of the todo.", todo.Properties["name"].Description); - Assert.Equal("Another description of the todo.", todo.Properties["description"].Description); + Assert.Equal("A description of the todo.\nAnother description of the todo.", todo.Properties["description"].Description); path = document.Paths["/type-with-examples"].Operations[HttpMethod.Post]; var typeWithExamples = path.RequestBody.Content["application/json"].Schema; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs index 82ae70006c10..4135d425dd0b 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs @@ -37,6 +37,7 @@ public async Task SupportsAllXmlTagsOnSchemas() app.MapPost("/generic-class", (GenericClass generic) => { }); app.MapPost("/generic-parent", (GenericParent parent) => { }); app.MapPost("/params-and-param-refs", (ParamsAndParamRefs refs) => { }); +app.MapPost("/xml-property-test", (XmlPropertyTestClass test) => { }); app.Run(); @@ -471,6 +472,37 @@ protected virtual void Dispose(bool disposing) // No-op } } + +/// +/// This class tests different XML comment scenarios for properties. +/// +public class XmlPropertyTestClass +{ + /// + /// A property with only summary tag. + /// + public string SummaryOnly { get; set; } + + /// + /// A property with only value tag. + /// + public string ValueOnly { get; set; } + + /// + /// A property with both summary and value. + /// + /// Additional value information. + public string BothSummaryAndValue { get; set; } + + /// This should be ignored for properties. + public string ReturnsOnly { get; set; } + + /// + /// A property with summary and returns. + /// + /// This should be ignored for properties. + public string SummaryAndReturns { get; set; } +} """; var generator = new XmlCommentGenerator(); await SnapshotTestHelper.Verify(source, generator, out var compilation); @@ -479,6 +511,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => var path = document.Paths["/example-class"].Operations[HttpMethod.Post]; var exampleClass = path.RequestBody.Content["application/json"].Schema; Assert.Equal("Every class and member should have a one sentence\nsummary describing its purpose.", exampleClass.Description, ignoreLineEndingDifferences: true); + // Label property has only tag -> uses value directly Assert.Equal("The `Label` property represents a label\nfor this instance.", exampleClass.Properties["label"].Description, ignoreLineEndingDifferences: true); path = document.Paths["/person"].Operations[HttpMethod.Post]; @@ -523,6 +556,26 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => path = document.Paths["/params-and-param-refs"].Operations[HttpMethod.Post]; var paramsAndParamRefs = path.RequestBody.Content["application/json"].Schema; Assert.Equal("This shows examples of typeparamref and typeparam tags", paramsAndParamRefs.Description); + + // Test new XML property documentation behavior + path = document.Paths["/xml-property-test"].Operations[HttpMethod.Post]; + var xmlPropertyTest = path.RequestBody.Content["application/json"].Schema; + Assert.Equal("This class tests different XML comment scenarios for properties.", xmlPropertyTest.Description); + + // Property with only -> uses summary directly + Assert.Equal("A property with only summary tag.", xmlPropertyTest.Properties["summaryOnly"].Description); + + // Property with only -> uses value directly + Assert.Equal("A property with only value tag.", xmlPropertyTest.Properties["valueOnly"].Description); + + // Property with both and -> combines with newline separator + Assert.Equal("A property with both summary and value.\nAdditional value information.", xmlPropertyTest.Properties["bothSummaryAndValue"].Description); + + // Property with only -> should be null (ignored) + Assert.Null(xmlPropertyTest.Properties["returnsOnly"].Description); + + // Property with and -> uses summary only, ignores returns + Assert.Equal("A property with summary and returns.", xmlPropertyTest.Properties["summaryAndReturns"].Description); }); } } diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs index 33544cd1a1af..dfc83ac56060 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs @@ -49,6 +49,7 @@ public async Task SupportsXmlCommentsOnOperationsFromMinimalApis() app.MapPost("/19", RouteHandlerExtensionMethods.Post19); app.MapGet("/20", RouteHandlerExtensionMethods.Get20); app.MapGet("/21", RouteHandlerExtensionMethods.Get21); +app.MapGet("/22", RouteHandlerExtensionMethods.Get22); app.Run(); @@ -249,6 +250,15 @@ public static IResult Get21([AsParameters] XmlDocPriorityParametersClass priorit { return TypedResults.Ok($"Processed parameters"); } + + /// + /// Tests summary and value documentation priority on AsParameters properties. + /// + /// Parameters testing summary vs value priority. + public static IResult Get22([AsParameters] SummaryValueParametersClass summaryValueParams) + { + return TypedResults.Ok($"Summary: {summaryValueParams.SummaryProperty}, Value: {summaryValueParams.ValueProperty}"); + } } public class FirstParameters @@ -371,6 +381,23 @@ public class XmlDocPriorityParametersClass /// Value-only description. public string? ValueOnlyProperty { get; set; } } + +public class SummaryValueParametersClass +{ + /// + /// Property with only summary documentation. + /// + public string? SummaryProperty { get; set; } + + /// + /// Property with summary that should be overridden by value. + /// + /// Value description that should take precedence over summary. + public string? ValueProperty { get; set; } + + /// Property with only value documentation. + public string? ValueOnlyProperty { get; set; } +} """; var generator = new XmlCommentGenerator(); await SnapshotTestHelper.Verify(source, generator, out var compilation); @@ -478,16 +505,29 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => Assert.Equal("Property with only summary documentation.", summaryOnlyParam.Description); var summaryAndReturnsParam = path22.Parameters.First(p => p.Name == "SummaryAndReturnsProperty"); - Assert.Equal("Returns-based description that should take precedence over summary.", summaryAndReturnsParam.Description); + Assert.Equal("Property with summary documentation that should be overridden.", summaryAndReturnsParam.Description); var allThreeParam = path22.Parameters.First(p => p.Name == "AllThreeProperty"); - Assert.Equal("Value-based description that should take highest precedence.", allThreeParam.Description); + Assert.Equal("Property with all three types of documentation.\nValue-based description that should take highest precedence.", allThreeParam.Description); var returnsOnlyParam = path22.Parameters.First(p => p.Name == "ReturnsOnlyProperty"); - Assert.Equal("Returns-only description.", returnsOnlyParam.Description); + Assert.Null(returnsOnlyParam.Description); var valueOnlyParam = path22.Parameters.First(p => p.Name == "ValueOnlyProperty"); Assert.Equal("Value-only description.", valueOnlyParam.Description); + + // Test summary and value documentation priority for AsParameters + var path23 = document.Paths["/22"].Operations[HttpMethod.Get]; + Assert.Equal("Tests summary and value documentation priority on AsParameters properties.", path23.Summary); + + var summaryParam = path23.Parameters.First(p => p.Name == "SummaryProperty"); + Assert.Equal("Property with only summary documentation.", summaryParam.Description); + + var valueParam = path23.Parameters.First(p => p.Name == "ValueProperty"); + Assert.Equal("Property with summary that should be overridden by value.\nValue description that should take precedence over summary.", valueParam.Description); + + var valueOnlyParam2 = path23.Parameters.First(p => p.Name == "ValueOnlyProperty"); + Assert.Equal("Property with only value documentation.", valueOnlyParam2.Description); }); } } diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs index 629b1322c376..f9b77d9f166e 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs @@ -206,9 +206,13 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => path = document.Paths["/todo-with-description"].Operations[HttpMethod.Post]; todo = path.RequestBody.Content["application/json"].Schema; + // Test different XML comment scenarios for properties: + // Id: only tag -> uses summary directly Assert.Equal("The identifier of the todo.", todo.Properties["id"].Description); + // Name: only tag -> uses value directly Assert.Equal("The name of the todo.", todo.Properties["name"].Description); - Assert.Equal("Another description of the todo.", todo.Properties["description"].Description); + // Description: both and tags -> combines with newline separator + Assert.Equal("A description of the the todo.\nAnother description of the todo.", todo.Properties["description"].Description); path = document.Paths["/type-with-examples"].Operations[HttpMethod.Post]; var typeWithExamples = path.RequestBody.Content["application/json"].Schema; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs index 80dc82a41ecc..ce2763fd112a 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs @@ -434,11 +434,20 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyDocId), out var propertyComment)) { var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name); + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } if (parameter is null) { if (operation.RequestBody is not null) { - operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + operation.RequestBody.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { var content = operation.RequestBody.Content?.Values; @@ -458,7 +467,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var targetOperationParameter = UnwrapOpenApiParameter(parameter); if (targetOperationParameter is not null) { - targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + targetOperationParameter.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { targetOperationParameter.Example = jsonString.Parse(); @@ -515,12 +524,21 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext // Apply comments from the property if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment)) { + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } 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!; + schema.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Example = jsonString.Parse(); @@ -529,7 +547,10 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext else { // Schema Reference - schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!; + if (!string.IsNullOrEmpty(description)) + { + schema.Metadata["x-ref-description"] = description; + } if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Metadata["x-ref-example"] = jsonString.Parse()!; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs index f5ced40af0d9..42aff6ae7205 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs @@ -463,11 +463,20 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyDocId), out var propertyComment)) { var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name); + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } if (parameter is null) { if (operation.RequestBody is not null) { - operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + operation.RequestBody.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { var content = operation.RequestBody.Content?.Values; @@ -487,7 +496,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var targetOperationParameter = UnwrapOpenApiParameter(parameter); if (targetOperationParameter is not null) { - targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + targetOperationParameter.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { targetOperationParameter.Example = jsonString.Parse(); @@ -544,12 +553,21 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext // Apply comments from the property if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment)) { + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } 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!; + schema.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Example = jsonString.Parse(); @@ -558,7 +576,10 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext else { // Schema Reference - schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!; + if (!string.IsNullOrEmpty(description)) + { + schema.Metadata["x-ref-description"] = description; + } if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Metadata["x-ref-example"] = jsonString.Parse()!; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs index f135f2fc5697..03379781d78f 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs @@ -148,6 +148,7 @@ type as a cref attribute. typeof expressions.", null, null, null, null, false, null, null, null)); cache.Add(@"T:ParamsAndParamRefs", new XmlComment(@"This shows examples of typeparamref and typeparam tags", null, null, null, null, false, null, null, null)); cache.Add(@"T:DisposableType", new XmlComment(@"A class that implements the IDisposable interface.", null, null, null, null, false, null, null, null)); + cache.Add(@"T:XmlPropertyTestClass", new XmlComment(@"This class tests different XML comment scenarios for properties.", null, null, null, null, false, null, null, null)); cache.Add(@"P:ExampleClass.Label", new XmlComment(null, null, @" The string? ExampleClass.Label is a `string` that you use for a label. Note that there isn't a way to provide a ""cref"" to @@ -160,6 +161,11 @@ Note that there isn't a way to provide a ""cref"" to cache.Add(@"P:GenericParent.TaskOfTupleProp", new XmlComment(@"This property is a generic type containing a tuple.", null, null, null, null, false, null, null, null)); cache.Add(@"P:GenericParent.TupleWithGenericProp", new XmlComment(@"This property is a tuple with a generic type inside.", null, null, null, null, false, null, null, null)); cache.Add(@"P:GenericParent.TupleWithNestedGenericProp", new XmlComment(@"This property is a tuple with a nested generic type inside.", null, null, null, null, false, null, null, null)); + cache.Add(@"P:XmlPropertyTestClass.SummaryOnly", new XmlComment(@"A property with only summary tag.", null, null, null, null, false, null, null, null)); + cache.Add(@"P:XmlPropertyTestClass.ValueOnly", new XmlComment(null, null, null, null, @"A property with only value tag.", false, null, null, null)); + cache.Add(@"P:XmlPropertyTestClass.BothSummaryAndValue", new XmlComment(@"A property with both summary and value.", null, null, null, @"Additional value information.", false, null, null, null)); + cache.Add(@"P:XmlPropertyTestClass.ReturnsOnly", new XmlComment(null, null, null, @"This should be ignored for properties.", null, false, null, null, null)); + cache.Add(@"P:XmlPropertyTestClass.SummaryAndReturns", new XmlComment(@"A property with summary and returns.", null, null, @"This should be ignored for properties.", null, false, null, null, null)); cache.Add(@"M:ExampleClass.Add(System.Int32,System.Int32)", new XmlComment(@"Adds two integers and returns the result.", null, null, @"The sum of two integers.", null, false, [@" ```int c = Math.Add(4, 5); if (c > 10) { @@ -555,11 +561,20 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyDocId), out var propertyComment)) { var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name); + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } if (parameter is null) { if (operation.RequestBody is not null) { - operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + operation.RequestBody.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { var content = operation.RequestBody.Content?.Values; @@ -579,7 +594,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var targetOperationParameter = UnwrapOpenApiParameter(parameter); if (targetOperationParameter is not null) { - targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + targetOperationParameter.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { targetOperationParameter.Example = jsonString.Parse(); @@ -636,12 +651,21 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext // Apply comments from the property if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment)) { + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } 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!; + schema.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Example = jsonString.Parse(); @@ -650,7 +674,10 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext else { // Schema Reference - schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!; + if (!string.IsNullOrEmpty(description)) + { + schema.Metadata["x-ref-description"] = description; + } if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Metadata["x-ref-example"] = jsonString.Parse()!; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs index 419dd3c5caff..0c2836cc9f2f 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs @@ -438,11 +438,20 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyDocId), out var propertyComment)) { var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name); + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } if (parameter is null) { if (operation.RequestBody is not null) { - operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + operation.RequestBody.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { var content = operation.RequestBody.Content?.Values; @@ -462,7 +471,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var targetOperationParameter = UnwrapOpenApiParameter(parameter); if (targetOperationParameter is not null) { - targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + targetOperationParameter.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { targetOperationParameter.Example = jsonString.Parse(); @@ -519,12 +528,21 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext // Apply comments from the property if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment)) { + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } 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!; + schema.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Example = jsonString.Parse(); @@ -533,7 +551,10 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext else { // Schema Reference - schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!; + if (!string.IsNullOrEmpty(description)) + { + schema.Metadata["x-ref-description"] = description; + } if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Metadata["x-ref-example"] = jsonString.Parse()!; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs index 7ddd295b8d29..c8da228d94d8 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs @@ -89,6 +89,9 @@ private static Dictionary GenerateCacheEntries() cache.Add(@"P:XmlDocPriorityParametersClass.AllThreeProperty", new XmlComment(@"Property with all three types of documentation.", null, null, @"Returns-based description that should be overridden by value.", @"Value-based description that should take highest precedence.", false, null, null, null)); cache.Add(@"P:XmlDocPriorityParametersClass.ReturnsOnlyProperty", new XmlComment(null, null, null, @"Returns-only description.", null, false, null, null, null)); cache.Add(@"P:XmlDocPriorityParametersClass.ValueOnlyProperty", new XmlComment(null, null, null, null, @"Value-only description.", false, null, null, null)); + cache.Add(@"P:SummaryValueParametersClass.SummaryProperty", new XmlComment(@"Property with only summary documentation.", null, null, null, null, false, null, null, null)); + cache.Add(@"P:SummaryValueParametersClass.ValueProperty", new XmlComment(@"Property with summary that should be overridden by value.", null, null, null, @"Value description that should take precedence over summary.", false, null, null, null)); + cache.Add(@"P:SummaryValueParametersClass.ValueOnlyProperty", new XmlComment(null, null, null, null, @"Property with only value documentation.", false, null, null, null)); cache.Add(@"M:RouteHandlerExtensionMethods.Get", new XmlComment(@"A summary of the action.", @"A description of the action.", null, @"Returns the greeting.", null, false, null, null, null)); cache.Add(@"M:RouteHandlerExtensionMethods.Get2(System.String)", new XmlComment(null, null, null, null, null, false, null, [new XmlParameterComment(@"name", @"The name of the person.", null, false)], [new XmlResponseComment(@"200", @"Returns the greeting.", @"")])); cache.Add(@"M:RouteHandlerExtensionMethods.Get3(System.String)", new XmlComment(null, null, null, @"Returns the greeting.", null, false, null, [new XmlParameterComment(@"name", @"The name of the person.", @"Testy McTester", false)], null)); @@ -115,6 +118,7 @@ private static Dictionary GenerateCacheEntries() cache.Add(@"M:RouteHandlerExtensionMethods.Post19(System.String,MixedParametersClass)", new XmlComment(@"Tests mixed regular and AsParameters with examples.", null, null, null, null, false, null, [new XmlParameterComment(@"regularParam", @"A regular parameter with documentation.", null, false), new XmlParameterComment(@"mixedParams", @"Mixed parameter class with various types.", null, false)], null)); cache.Add(@"M:RouteHandlerExtensionMethods.Get20(BindingSourceParametersClass)", new XmlComment(@"Tests AsParameters with different binding sources.", null, null, null, null, false, null, [new XmlParameterComment(@"bindingParams", @"Parameters from different sources.", null, false)], null)); cache.Add(@"M:RouteHandlerExtensionMethods.Get21(XmlDocPriorityParametersClass)", new XmlComment(@"Tests XML documentation priority order (value > returns > summary).", null, null, null, null, false, null, [new XmlParameterComment(@"priorityParams", @"Parameters demonstrating XML doc priority.", null, false)], null)); + cache.Add(@"M:RouteHandlerExtensionMethods.Get22(SummaryValueParametersClass)", new XmlComment(@"Tests summary and value documentation priority on AsParameters properties.", null, null, null, null, false, null, [new XmlParameterComment(@"summaryValueParams", @"Parameters testing summary vs value priority.", null, false)], null)); return cache; } @@ -478,11 +482,20 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyDocId), out var propertyComment)) { var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name); + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } if (parameter is null) { if (operation.RequestBody is not null) { - operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + operation.RequestBody.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { var content = operation.RequestBody.Content?.Values; @@ -502,7 +515,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var targetOperationParameter = UnwrapOpenApiParameter(parameter); if (targetOperationParameter is not null) { - targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + targetOperationParameter.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { targetOperationParameter.Example = jsonString.Parse(); @@ -559,12 +572,21 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext // Apply comments from the property if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment)) { + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } 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!; + schema.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Example = jsonString.Parse(); @@ -573,7 +595,10 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext else { // Schema Reference - schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!; + if (!string.IsNullOrEmpty(description)) + { + schema.Metadata["x-ref-description"] = description; + } if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Metadata["x-ref-example"] = jsonString.Parse()!; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs index f97dae09882c..e192067879b7 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs @@ -464,11 +464,20 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyDocId), out var propertyComment)) { var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name); + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } if (parameter is null) { if (operation.RequestBody is not null) { - operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + operation.RequestBody.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { var content = operation.RequestBody.Content?.Values; @@ -488,7 +497,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var targetOperationParameter = UnwrapOpenApiParameter(parameter); if (targetOperationParameter is not null) { - targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + targetOperationParameter.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { targetOperationParameter.Example = jsonString.Parse(); @@ -545,12 +554,21 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext // Apply comments from the property if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment)) { + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } 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!; + schema.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Example = jsonString.Parse(); @@ -559,7 +577,10 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext else { // Schema Reference - schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!; + if (!string.IsNullOrEmpty(description)) + { + schema.Metadata["x-ref-description"] = description; + } if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Metadata["x-ref-example"] = jsonString.Parse()!; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs index c60e8c189812..62eca1ce5fa6 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs @@ -443,11 +443,20 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyDocId), out var propertyComment)) { var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name); + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } if (parameter is null) { if (operation.RequestBody is not null) { - operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + operation.RequestBody.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { var content = operation.RequestBody.Content?.Values; @@ -467,7 +476,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var targetOperationParameter = UnwrapOpenApiParameter(parameter); if (targetOperationParameter is not null) { - targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + targetOperationParameter.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { targetOperationParameter.Example = jsonString.Parse(); @@ -524,12 +533,21 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext // Apply comments from the property if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment)) { + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } 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!; + schema.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Example = jsonString.Parse(); @@ -538,7 +556,10 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext else { // Schema Reference - schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!; + if (!string.IsNullOrEmpty(description)) + { + schema.Metadata["x-ref-description"] = description; + } if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Metadata["x-ref-example"] = jsonString.Parse()!; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs index 5e2aefb507a9..2bea3547fc7b 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs @@ -435,11 +435,20 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyDocId), out var propertyComment)) { var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name); + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } if (parameter is null) { if (operation.RequestBody is not null) { - operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + operation.RequestBody.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { var content = operation.RequestBody.Content?.Values; @@ -459,7 +468,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var targetOperationParameter = UnwrapOpenApiParameter(parameter); if (targetOperationParameter is not null) { - targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary; + targetOperationParameter.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { targetOperationParameter.Example = jsonString.Parse(); @@ -516,12 +525,21 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext // Apply comments from the property if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment)) { + var description = propertyComment.Summary; + if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) + { + description = $"{description}\n{propertyComment.Value}"; + } + else if (string.IsNullOrEmpty(description)) + { + description = propertyComment.Value; + } 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!; + schema.Description = description; if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Example = jsonString.Parse(); @@ -530,7 +548,10 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext else { // Schema Reference - schema.Metadata["x-ref-description"] = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary!; + if (!string.IsNullOrEmpty(description)) + { + schema.Metadata["x-ref-description"] = description; + } if (propertyComment.Examples?.FirstOrDefault() is { } jsonString) { schema.Metadata["x-ref-example"] = jsonString.Parse()!; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_0/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=xml.verified.txt b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_0/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=xml.verified.txt index 9eed2206b116..d2b295c23ab6 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_0/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=xml.verified.txt +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_0/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=xml.verified.txt @@ -341,7 +341,7 @@ }, "description": { "type": "string", - "description": "Another description of the todo." + "description": "A description of the the todo.\nAnother description of the todo." } } }, diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_1/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=xml.verified.txt b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_1/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=xml.verified.txt index 4a8829575928..7a4b01a03316 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_1/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=xml.verified.txt +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApi3_1/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=xml.verified.txt @@ -341,7 +341,7 @@ }, "description": { "type": "string", - "description": "Another description of the todo." + "description": "A description of the the todo.\nAnother description of the todo." } } }, diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant.verified.txt b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant.verified.txt index 4094879f54a8..a5abfc5f0433 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant.verified.txt +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant.verified.txt @@ -1845,7 +1845,7 @@ }, "description": { "type": "string", - "description": "Another description of the todo." + "description": "A description of the the todo.\nAnother description of the todo." } } }, From bc9718ab8663ecc96a35eb65bd3940dcd380ab5f Mon Sep 17 00:00:00 2001 From: Safia Abdalla Date: Mon, 11 Aug 2025 16:40:32 -0700 Subject: [PATCH 2/5] Use Environment.Newline --- src/OpenApi/gen/XmlCommentGenerator.Emitter.cs | 4 ++-- ...tAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...tionalTexts#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...gsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...Controllers#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...MinimalApis#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...tsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...aReferences#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...onIdFormats#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- 9 files changed, 18 insertions(+), 18 deletions(-) diff --git a/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs b/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs index b7bff6ff1282..15c134b4569b 100644 --- a/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs +++ b/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs @@ -455,7 +455,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -545,7 +545,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs index ce2763fd112a..54699ddfa7db 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs @@ -437,7 +437,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -527,7 +527,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs index 42aff6ae7205..bd7e9381cc14 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs @@ -466,7 +466,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -556,7 +556,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs index 03379781d78f..d3f357dc4f3b 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs @@ -564,7 +564,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -654,7 +654,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs index 0c2836cc9f2f..3bac09ba28a2 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs @@ -441,7 +441,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -531,7 +531,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs index c8da228d94d8..0169e0fdbcfe 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs @@ -485,7 +485,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -575,7 +575,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs index e192067879b7..906c5b95f597 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs @@ -467,7 +467,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -557,7 +557,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs index 62eca1ce5fa6..f2ad225b4886 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs @@ -446,7 +446,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -536,7 +536,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs index 2bea3547fc7b..f70d2a3a90bb 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs @@ -438,7 +438,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -528,7 +528,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}\n{propertyComment.Value}"; + description = $"{description}{Environment.NewLine}{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { From 2fe9e40d1a7c73d56104cdfb73e38f4540c39387 Mon Sep 17 00:00:00 2001 From: Safia Abdalla Date: Mon, 11 Aug 2025 17:04:35 -0700 Subject: [PATCH 3/5] Use Environment.Newline in tests --- .../AdditionalTextsTests.Schemas.cs | 2 +- .../CompletenessTests.cs | 2 +- .../OperationTests.MinimalApis.cs | 4 ++-- .../SchemaTests.cs | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs index 9c674c93c60d..a4b46670577f 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs @@ -215,7 +215,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, additionalAssemblies, docume todo = path.RequestBody.Content["application/json"].Schema; Assert.Equal("The identifier of the todo.", todo.Properties["id"].Description); Assert.Equal("The name of the todo.", todo.Properties["name"].Description); - Assert.Equal("A description of the todo.\nAnother description of the todo.", todo.Properties["description"].Description); + Assert.Equal($"A description of the todo.{Environment.NewLine}Another description of the todo.", todo.Properties["description"].Description); path = document.Paths["/type-with-examples"].Operations[HttpMethod.Post]; var typeWithExamples = path.RequestBody.Content["application/json"].Schema; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs index 4135d425dd0b..e9e722276f10 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs @@ -569,7 +569,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => Assert.Equal("A property with only value tag.", xmlPropertyTest.Properties["valueOnly"].Description); // Property with both and -> combines with newline separator - Assert.Equal("A property with both summary and value.\nAdditional value information.", xmlPropertyTest.Properties["bothSummaryAndValue"].Description); + Assert.Equal($"A property with both summary and value.{Environment.NewLine}Additional value information.", xmlPropertyTest.Properties["bothSummaryAndValue"].Description); // Property with only -> should be null (ignored) Assert.Null(xmlPropertyTest.Properties["returnsOnly"].Description); diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs index dfc83ac56060..15594ad76974 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs @@ -508,7 +508,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => Assert.Equal("Property with summary documentation that should be overridden.", summaryAndReturnsParam.Description); var allThreeParam = path22.Parameters.First(p => p.Name == "AllThreeProperty"); - Assert.Equal("Property with all three types of documentation.\nValue-based description that should take highest precedence.", allThreeParam.Description); + Assert.Equal($"Property with all three types of documentation.{Environment.NewLine}Value-based description that should take highest precedence.", allThreeParam.Description); var returnsOnlyParam = path22.Parameters.First(p => p.Name == "ReturnsOnlyProperty"); Assert.Null(returnsOnlyParam.Description); @@ -524,7 +524,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => Assert.Equal("Property with only summary documentation.", summaryParam.Description); var valueParam = path23.Parameters.First(p => p.Name == "ValueProperty"); - Assert.Equal("Property with summary that should be overridden by value.\nValue description that should take precedence over summary.", valueParam.Description); + Assert.Equal($"Property with summary that should be overridden by value.{Environment.NewLine}Value description that should take precedence over summary.", valueParam.Description); var valueOnlyParam2 = path23.Parameters.First(p => p.Name == "ValueOnlyProperty"); Assert.Equal("Property with only value documentation.", valueOnlyParam2.Description); diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs index f9b77d9f166e..93428984d88f 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs @@ -212,7 +212,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => // Name: only tag -> uses value directly Assert.Equal("The name of the todo.", todo.Properties["name"].Description); // Description: both and tags -> combines with newline separator - Assert.Equal("A description of the the todo.\nAnother description of the todo.", todo.Properties["description"].Description); + Assert.Equal($"A description of the the todo.{Environment.NewLine}Another description of the todo.", todo.Properties["description"].Description); path = document.Paths["/type-with-examples"].Operations[HttpMethod.Post]; var typeWithExamples = path.RequestBody.Content["application/json"].Schema; From c5f2f11544640b13cb04115d203a88a351e8fd54 Mon Sep 17 00:00:00 2001 From: Safia Abdalla Date: Mon, 11 Aug 2025 21:38:07 -0700 Subject: [PATCH 4/5] Update newlines in tests --- .../Integration/OpenApiDocumentIntegrationTests.cs | 2 +- .../Integration/OpenApiDocumentLocalizationTests.cs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentIntegrationTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentIntegrationTests.cs index 1ce73bd3e57c..0a0d66ea6649 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentIntegrationTests.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentIntegrationTests.cs @@ -44,7 +44,7 @@ public async Task VerifyOpenApiDocument(string documentName, OpenApiSpecVersion ? Path.Combine(Environment.GetEnvironmentVariable("HELIX_WORKITEM_ROOT"), "Integration", "snapshots") : "snapshots"; var outputDirectory = Path.Combine(baseSnapshotsDirectory, version.ToString()); - await Verify(json) + await Verify(json.ReplaceLineEndings("\n")) .UseDirectory(outputDirectory) .UseParameters(documentName); } diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentLocalizationTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentLocalizationTests.cs index e2480db6e048..d977d0341792 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentLocalizationTests.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentLocalizationTests.cs @@ -14,7 +14,7 @@ public async Task VerifyOpenApiDocumentIsInvariant() var outputDirectory = SkipOnHelixAttribute.OnHelix() ? Path.Combine(Environment.GetEnvironmentVariable("HELIX_WORKITEM_ROOT"), "Integration", "snapshots") : "snapshots"; - await Verify(json) + await Verify(json.ReplaceLineEndings("\n")) .UseDirectory(outputDirectory); } } From 7e83f6f3178dc966646be4d07b35d0daedfde413 Mon Sep 17 00:00:00 2001 From: Safia Abdalla Date: Mon, 11 Aug 2025 21:55:07 -0700 Subject: [PATCH 5/5] Back to newlines --- src/OpenApi/gen/XmlCommentGenerator.Emitter.cs | 4 ++-- .../AdditionalTextsTests.Schemas.cs | 2 +- .../CompletenessTests.cs | 2 +- .../OperationTests.MinimalApis.cs | 4 ++-- .../SchemaTests.cs | 2 +- ...tAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...tionalTexts#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...gsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...Controllers#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...MinimalApis#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...tsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...aReferences#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- ...onIdFormats#OpenApiXmlCommentSupport.generated.verified.cs | 4 ++-- .../Integration/OpenApiDocumentIntegrationTests.cs | 2 +- .../Integration/OpenApiDocumentLocalizationTests.cs | 2 +- 15 files changed, 25 insertions(+), 25 deletions(-) diff --git a/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs b/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs index 15c134b4569b..b7bff6ff1282 100644 --- a/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs +++ b/src/OpenApi/gen/XmlCommentGenerator.Emitter.cs @@ -455,7 +455,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -545,7 +545,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs index a4b46670577f..d349f172b24e 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs @@ -215,7 +215,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, additionalAssemblies, docume todo = path.RequestBody.Content["application/json"].Schema; Assert.Equal("The identifier of the todo.", todo.Properties["id"].Description); Assert.Equal("The name of the todo.", todo.Properties["name"].Description); - Assert.Equal($"A description of the todo.{Environment.NewLine}Another description of the todo.", todo.Properties["description"].Description); + Assert.Equal($"A description of the todo.\nAnother description of the todo.", todo.Properties["description"].Description); path = document.Paths["/type-with-examples"].Operations[HttpMethod.Post]; var typeWithExamples = path.RequestBody.Content["application/json"].Schema; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs index e9e722276f10..24656b12c63f 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs @@ -569,7 +569,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => Assert.Equal("A property with only value tag.", xmlPropertyTest.Properties["valueOnly"].Description); // Property with both and -> combines with newline separator - Assert.Equal($"A property with both summary and value.{Environment.NewLine}Additional value information.", xmlPropertyTest.Properties["bothSummaryAndValue"].Description); + Assert.Equal($"A property with both summary and value.\nAdditional value information.", xmlPropertyTest.Properties["bothSummaryAndValue"].Description); // Property with only -> should be null (ignored) Assert.Null(xmlPropertyTest.Properties["returnsOnly"].Description); diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs index 15594ad76974..dad4380e2f9a 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs @@ -508,7 +508,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => Assert.Equal("Property with summary documentation that should be overridden.", summaryAndReturnsParam.Description); var allThreeParam = path22.Parameters.First(p => p.Name == "AllThreeProperty"); - Assert.Equal($"Property with all three types of documentation.{Environment.NewLine}Value-based description that should take highest precedence.", allThreeParam.Description); + Assert.Equal($"Property with all three types of documentation.\nValue-based description that should take highest precedence.", allThreeParam.Description); var returnsOnlyParam = path22.Parameters.First(p => p.Name == "ReturnsOnlyProperty"); Assert.Null(returnsOnlyParam.Description); @@ -524,7 +524,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => Assert.Equal("Property with only summary documentation.", summaryParam.Description); var valueParam = path23.Parameters.First(p => p.Name == "ValueProperty"); - Assert.Equal($"Property with summary that should be overridden by value.{Environment.NewLine}Value description that should take precedence over summary.", valueParam.Description); + Assert.Equal($"Property with summary that should be overridden by value.\nValue description that should take precedence over summary.", valueParam.Description); var valueOnlyParam2 = path23.Parameters.First(p => p.Name == "ValueOnlyProperty"); Assert.Equal("Property with only value documentation.", valueOnlyParam2.Description); diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs index 93428984d88f..9fcd24ca2dec 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/SchemaTests.cs @@ -212,7 +212,7 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document => // Name: only tag -> uses value directly Assert.Equal("The name of the todo.", todo.Properties["name"].Description); // Description: both and tags -> combines with newline separator - Assert.Equal($"A description of the the todo.{Environment.NewLine}Another description of the todo.", todo.Properties["description"].Description); + Assert.Equal($"A description of the the todo.\nAnother description of the todo.", todo.Properties["description"].Description); path = document.Paths["/type-with-examples"].Operations[HttpMethod.Post]; var typeWithExamples = path.RequestBody.Content["application/json"].Schema; diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs index 54699ddfa7db..ce2763fd112a 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs @@ -437,7 +437,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -527,7 +527,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs index bd7e9381cc14..42aff6ae7205 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs @@ -466,7 +466,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -556,7 +556,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs index d3f357dc4f3b..03379781d78f 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs @@ -564,7 +564,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -654,7 +654,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs index 3bac09ba28a2..0c2836cc9f2f 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs @@ -441,7 +441,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -531,7 +531,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs index 0169e0fdbcfe..c8da228d94d8 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromMinimalApis#OpenApiXmlCommentSupport.generated.verified.cs @@ -485,7 +485,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -575,7 +575,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs index 906c5b95f597..e192067879b7 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.SupportsXmlCommentsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs @@ -467,7 +467,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -557,7 +557,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs index f2ad225b4886..62eca1ce5fa6 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/SchemaTests.XmlCommentsOnPropertiesShouldApplyToSchemaReferences#OpenApiXmlCommentSupport.generated.verified.cs @@ -446,7 +446,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -536,7 +536,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs index f70d2a3a90bb..2bea3547fc7b 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/XmlCommentDocumentationIdTests.CanMergeXmlCommentsWithDifferentDocumentationIdFormats#OpenApiXmlCommentSupport.generated.verified.cs @@ -438,7 +438,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { @@ -528,7 +528,7 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var description = propertyComment.Summary; if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) { - description = $"{description}{Environment.NewLine}{propertyComment.Value}"; + description = $"{description}\n{propertyComment.Value}"; } else if (string.IsNullOrEmpty(description)) { diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentIntegrationTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentIntegrationTests.cs index 0a0d66ea6649..1ce73bd3e57c 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentIntegrationTests.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentIntegrationTests.cs @@ -44,7 +44,7 @@ public async Task VerifyOpenApiDocument(string documentName, OpenApiSpecVersion ? Path.Combine(Environment.GetEnvironmentVariable("HELIX_WORKITEM_ROOT"), "Integration", "snapshots") : "snapshots"; var outputDirectory = Path.Combine(baseSnapshotsDirectory, version.ToString()); - await Verify(json.ReplaceLineEndings("\n")) + await Verify(json) .UseDirectory(outputDirectory) .UseParameters(documentName); } diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentLocalizationTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentLocalizationTests.cs index d977d0341792..e2480db6e048 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentLocalizationTests.cs +++ b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/OpenApiDocumentLocalizationTests.cs @@ -14,7 +14,7 @@ public async Task VerifyOpenApiDocumentIsInvariant() var outputDirectory = SkipOnHelixAttribute.OnHelix() ? Path.Combine(Environment.GetEnvironmentVariable("HELIX_WORKITEM_ROOT"), "Integration", "snapshots") : "snapshots"; - await Verify(json.ReplaceLineEndings("\n")) + await Verify(json) .UseDirectory(outputDirectory); } }