Skip to content

Fix OpenAPI request body description uses wrong parameter comment#65827

Open
BloodShop wants to merge 4 commits intodotnet:mainfrom
BloodShop:fix/openapi-request-body-comment
Open

Fix OpenAPI request body description uses wrong parameter comment#65827
BloodShop wants to merge 4 commits intodotnet:mainfrom
BloodShop:fix/openapi-request-body-comment

Conversation

@BloodShop
Copy link

Fixes issue #65805.

When an endpoint has multiple parameters including [FromBody] and injected dependencies (like ILogger or CancellationToken), the request body description was incorrectly using the comment from the LAST parameter instead of the [FromBody] parameter.

Example:

public async Task<Ok<int>> PostSampleData(
    [FromBody] SomeData data,  // Comment: "Sample data provided by the user"
    [FromServices] ILogger logger,
    CancellationToken cancellation  // Comment: "Injected cancellation token"
)

Expected request body description: "Sample data provided by the user."
Actual request body description: "Injected cancellation token."

The bug was in XmlCommentGenerator.Emitter where it loops through all parameters and assigns any unmatched parameter comment to the request body. The last iteration would overwrite previous ones.

Fix: Only use a parameter comment for the request body if it has [FromBody] or is a complex type.

…(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).
@BloodShop BloodShop requested a review from a team as a code owner March 18, 2026 11:03
@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 18, 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 18, 2026
@dotnet-policy-service
Copy link
Contributor

Thanks for your PR, @@BloodShop. Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

@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 18, 2026
@martincostello
Copy link
Member

This PR should have test coverage for what's being fixed.

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.
@BloodShop
Copy link
Author

Test coverage added. New regression test verifies that when an endpoint has [FromBody] followed by [FromServices] and CancellationToken parameters, the request body description uses the [FromBody] parameter's XML comment, not the last parameter's.

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
Copy link
Author

Fixed the test failures. The issue was using reflection-based attribute heuristics to identify the request body parameter. Switched to using ApiExplorer's ParameterDescription binding source which is deterministic and already knows which parameter is the body.

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.

2 participants