Skip to content

Commit da93209

Browse files
captainsafiacaptainsafia
committed
Feedback and more tests
1 parent 0645c36 commit da93209

9 files changed

+93
-24
lines changed

‎src/OpenApi/gen/XmlCommentGenerator.Emitter.cs

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -456,17 +456,18 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform
456456
{
457457
if (operation.RequestBody is not null)
458458
{
459-
operation.RequestBody.Description = propertyComment.Summary ?? propertyComment.Description;
459+
operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
460460
if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
461461
{
462462
var content = operation.RequestBody.Content?.Values;
463+
var parsedExample = jsonString.Parse();
463464
if (content is null)
464465
{
465466
continue;
466467
}
467468
foreach (var mediaType in content)
468469
{
469-
mediaType.Example = jsonString.Parse();
470+
mediaType.Example = parsedExample;
470471
}
471472
}
472473
}
@@ -475,7 +476,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform
475476
var targetOperationParameter = UnwrapOpenApiParameter(parameter);
476477
if (targetOperationParameter is not null)
477478
{
478-
targetOperationParameter.Description = propertyComment.Summary ?? propertyComment.Description;
479+
targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
479480
if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
480481
{
481482
targetOperationParameter.Example = jsonString.Parse();

‎src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ public async Task SupportsXmlCommentsOnOperationsFromMinimalApis()
4848
app.MapPost("/18", RouteHandlerExtensionMethods.Post18);
4949
app.MapPost("/19", RouteHandlerExtensionMethods.Post19);
5050
app.MapGet("/20", RouteHandlerExtensionMethods.Get20);
51+
app.MapGet("/21", RouteHandlerExtensionMethods.Get21);
5152
5253
app.Run();
5354
@@ -239,6 +240,15 @@ public static IResult Get20([AsParameters] BindingSourceParametersClass bindingP
239240
{
240241
return TypedResults.Ok($"Query: {bindingParams.QueryParam}, Header: {bindingParams.HeaderParam}");
241242
}
243+
244+
/// <summary>
245+
/// Tests XML documentation priority order (value > returns > summary).
246+
/// </summary>
247+
/// <param name="priorityParams">Parameters demonstrating XML doc priority.</param>
248+
public static IResult Get21([AsParameters] XmlDocPriorityParametersClass priorityParams)
249+
{
250+
return TypedResults.Ok($"Processed parameters");
251+
}
242252
}
243253
244254
public class FirstParameters
@@ -334,6 +344,33 @@ public class BindingSourceParametersClass
334344
[FromHeader]
335345
public string? HeaderParam { get; set; }
336346
}
347+
348+
public class XmlDocPriorityParametersClass
349+
{
350+
/// <summary>
351+
/// Property with only summary documentation.
352+
/// </summary>
353+
public string? SummaryOnlyProperty { get; set; }
354+
355+
/// <summary>
356+
/// Property with summary documentation that should be overridden.
357+
/// </summary>
358+
/// <returns>Returns-based description that should take precedence over summary.</returns>
359+
public string? SummaryAndReturnsProperty { get; set; }
360+
361+
/// <summary>
362+
/// Property with all three types of documentation.
363+
/// </summary>
364+
/// <returns>Returns-based description that should be overridden by value.</returns>
365+
/// <value>Value-based description that should take highest precedence.</value>
366+
public string? AllThreeProperty { get; set; }
367+
368+
/// <returns>Returns-only description.</returns>
369+
public string? ReturnsOnlyProperty { get; set; }
370+
371+
/// <value>Value-only description.</value>
372+
public string? ValueOnlyProperty { get; set; }
373+
}
337374
""";
338375
var generator = new XmlCommentGenerator();
339376
await SnapshotTestHelper.Verify(source, generator, out var compilation);
@@ -433,6 +470,24 @@ await SnapshotTestHelper.VerifyOpenApi(compilation, document =>
433470
Assert.Equal("Tests AsParameters with different binding sources.", path20.Summary);
434471
Assert.Equal("Query parameter from URL.", path20.Parameters[0].Description);
435472
Assert.Equal("Header value from request.", path20.Parameters[1].Description);
473+
474+
// Test XML documentation priority order: value > returns > summary
475+
var path22 = document.Paths["/21"].Operations[HttpMethod.Get];
476+
// Find parameters by name for clearer assertions
477+
var summaryOnlyParam = path22.Parameters.First(p => p.Name == "SummaryOnlyProperty");
478+
Assert.Equal("Property with only summary documentation.", summaryOnlyParam.Description);
479+
480+
var summaryAndReturnsParam = path22.Parameters.First(p => p.Name == "SummaryAndReturnsProperty");
481+
Assert.Equal("Returns-based description that should take precedence over summary.", summaryAndReturnsParam.Description);
482+
483+
var allThreeParam = path22.Parameters.First(p => p.Name == "AllThreeProperty");
484+
Assert.Equal("Value-based description that should take highest precedence.", allThreeParam.Description);
485+
486+
var returnsOnlyParam = path22.Parameters.First(p => p.Name == "ReturnsOnlyProperty");
487+
Assert.Equal("Returns-only description.", returnsOnlyParam.Description);
488+
489+
var valueOnlyParam = path22.Parameters.First(p => p.Name == "ValueOnlyProperty");
490+
Assert.Equal("Value-only description.", valueOnlyParam.Description);
436491
});
437492
}
438493
}

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -438,17 +438,18 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform
438438
{
439439
if (operation.RequestBody is not null)
440440
{
441-
operation.RequestBody.Description = propertyComment.Summary ?? propertyComment.Description;
441+
operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
442442
if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
443443
{
444444
var content = operation.RequestBody.Content?.Values;
445+
var parsedExample = jsonString.Parse();
445446
if (content is null)
446447
{
447448
continue;
448449
}
449450
foreach (var mediaType in content)
450451
{
451-
mediaType.Example = jsonString.Parse();
452+
mediaType.Example = parsedExample;
452453
}
453454
}
454455
}
@@ -457,7 +458,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform
457458
var targetOperationParameter = UnwrapOpenApiParameter(parameter);
458459
if (targetOperationParameter is not null)
459460
{
460-
targetOperationParameter.Description = propertyComment.Summary ?? propertyComment.Description;
461+
targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
461462
if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
462463
{
463464
targetOperationParameter.Example = jsonString.Parse();

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -467,17 +467,18 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform
467467
{
468468
if (operation.RequestBody is not null)
469469
{
470-
operation.RequestBody.Description = propertyComment.Summary ?? propertyComment.Description;
470+
operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
471471
if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
472472
{
473473
var content = operation.RequestBody.Content?.Values;
474+
var parsedExample = jsonString.Parse();
474475
if (content is null)
475476
{
476477
continue;
477478
}
478479
foreach (var mediaType in content)
479480
{
480-
mediaType.Example = jsonString.Parse();
481+
mediaType.Example = parsedExample;
481482
}
482483
}
483484
}
@@ -486,7 +487,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform
486487
var targetOperationParameter = UnwrapOpenApiParameter(parameter);
487488
if (targetOperationParameter is not null)
488489
{
489-
targetOperationParameter.Description = propertyComment.Summary ?? propertyComment.Description;
490+
targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
490491
if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
491492
{
492493
targetOperationParameter.Example = jsonString.Parse();

‎src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -559,17 +559,18 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform
559559
{
560560
if (operation.RequestBody is not null)
561561
{
562-
operation.RequestBody.Description = propertyComment.Summary ?? propertyComment.Description;
562+
operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
563563
if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
564564
{
565565
var content = operation.RequestBody.Content?.Values;
566+
var parsedExample = jsonString.Parse();
566567
if (content is null)
567568
{
568569
continue;
569570
}
570571
foreach (var mediaType in content)
571572
{
572-
mediaType.Example = jsonString.Parse();
573+
mediaType.Example = parsedExample;
573574
}
574575
}
575576
}
@@ -578,7 +579,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform
578579
var targetOperationParameter = UnwrapOpenApiParameter(parameter);
579580
if (targetOperationParameter is not null)
580581
{
581-
targetOperationParameter.Description = propertyComment.Summary ?? propertyComment.Description;
582+
targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
582583
if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
583584
{
584585
targetOperationParameter.Example = jsonString.Parse();

‎src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -442,17 +442,18 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform
442442
{
443443
if (operation.RequestBody is not null)
444444
{
445-
operation.RequestBody.Description = propertyComment.Summary ?? propertyComment.Description;
445+
operation.RequestBody.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
446446
if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
447447
{
448448
var content = operation.RequestBody.Content?.Values;
449+
var parsedExample = jsonString.Parse();
449450
if (content is null)
450451
{
451452
continue;
452453
}
453454
foreach (var mediaType in content)
454455
{
455-
mediaType.Example = jsonString.Parse();
456+
mediaType.Example = parsedExample;
456457
}
457458
}
458459
}
@@ -461,7 +462,7 @@ public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransform
461462
var targetOperationParameter = UnwrapOpenApiParameter(parameter);
462463
if (targetOperationParameter is not null)
463464
{
464-
targetOperationParameter.Description = propertyComment.Summary ?? propertyComment.Description;
465+
targetOperationParameter.Description = propertyComment.Value ?? propertyComment.Returns ?? propertyComment.Summary;
465466
if (propertyComment.Examples?.FirstOrDefault() is { } jsonString)
466467
{
467468
targetOperationParameter.Example = jsonString.Parse();

0 commit comments

Comments
 (0)