Skip to content

fix: OpenAPI request body description uses correct parameter comment#65898

Closed
BloodShop wants to merge 4 commits intodotnet:mainfrom
BloodShop:fix/openapi-request-body-description-clean
Closed

fix: OpenAPI request body description uses correct parameter comment#65898
BloodShop wants to merge 4 commits intodotnet:mainfrom
BloodShop:fix/openapi-request-body-description-clean

Conversation

@BloodShop
Copy link

Summary

This PR fixes issue #65805 where OpenAPI request body descriptions were incorrectly using the last parameter's XML comment instead of the [FromBody] parameter's comment.

Problem

When an endpoint had multiple parameters (e.g., [FromBody] parameter followed by [FromServices] or CancellationToken), the OpenAPI generator would incorrectly assign the last parameter's XML comment to the request body description instead of using the comment from the parameter that actually represents the request body.

Root Cause

The original loop that assigns parameter comments would iterate through all parameters and assign any unmatched parameter's comment to the request body. This caused the last iteration (usually an injected dependency like CancellationToken) to overwrite the correct [FromBody] parameter's comment.

Solution

Updated the logic to:

  1. Use ParameterDescription.Source from ApiExplorer to correctly identify which parameter represents the request body
  2. Only assign a parameter's comment to the request body if it has a binding source that indicates it's for request body (Body, FormFile, or Form)
  3. Prevent overwriting requestBody.Description if already set, ensuring the correct comment is preserved

Files Modified

  • src/OpenApi/gen/XmlCommentGenerator.Emitter.cs - Core fix to parameter comment assignment logic
  • src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.MinimalApis.cs - Added regression test

Benefits

  • ✅ Request body descriptions now correctly use the [FromBody] parameter's XML comment
  • ✅ No more confusion with injected dependencies overwriting correct comments
  • ✅ Robust identification using actual binding source instead of heuristics
  • ✅ Comprehensive test coverage to prevent regression

Testing

Added regression test that verifies when an endpoint has [FromBody] followed by [FromServices] and CancellationToken parameters, the request body description uses the [FromBody] parameter's comment ("Sample data provided by the user") and not the last parameter's comment ("Injected cancellation token").

This is a clean version that contains only the OpenAPI fix without the infrastructure changes that were causing test failures in the previous PR.

Fixes #65805

…(issue dotnet#65805)

When an endpoint has multiple parameters, the request body description should use
the [FromBody] parameter's XML comment, not the last unmatched parameter's comment.

The bug was in the loop that assigns parameter comments. It would iterate through
all parameters and assign any unmatched parameter's comment to the request body,
causing the last iteration (usually an injected dependency like CancellationToken)
to overwrite the correct [FromBody] parameter's comment.

Fix: Only use a parameter's comment for the request body if it has a [FromBody]
attribute or is a complex type (indicating it's meant for request body binding).
Verifies that when an endpoint has [FromBody] followed by other parameters
([FromServices], CancellationToken), the request body description uses the
[FromBody] parameter's comment, not the last parameter's comment.
Switched from attribute-based heuristics to using the actual ParameterDescription
binding source to identify which parameter comment belongs to the request body.

Also prevent overwriting requestBody.Description if already set, ensuring the
correct parameter's comment is preserved.
@BloodShop BloodShop requested a review from a team as a code owner March 22, 2026 13:44
@github-actions github-actions bot added the needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically label Mar 22, 2026
@dotnet-policy-service dotnet-policy-service bot added the community-contribution Indicates that the PR has been added by a community member label Mar 22, 2026
@martincostello martincostello added feature-openapi area-minimal Includes minimal APIs, endpoint filters, parameter binding, request delegate generator etc and removed needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically labels Mar 22, 2026
@martincostello
Copy link
Member

Appears to be an exact duplicate of #65827.

@BloodShop
Copy link
Author

Closing duplicate PR. Updated the original PR #65827 with clean commits instead. Sorry for the confusion!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-minimal Includes minimal APIs, endpoint filters, parameter binding, request delegate generator etc community-contribution Indicates that the PR has been added by a community member feature-openapi

Projects

None yet

Development

Successfully merging this pull request may close these issues.

OpenAPI document generation uses wrong XML comments

2 participants