Respect IModelNameProvider when matching OpenAPI parameters by khellang · Pull Request #64535 · dotnet/aspnetcore

khellang · 2025-11-26T08:45:57Z

Description

This makes sure any attribute implementing IModelNameProvider is respected when matching OpenAPI operation parameters with .NET action parameters.

It also replaces the CancellationToken workaround from the initial review with a proper check against BindingSource.Body, so documentation for parameters that aren't part of the OpenAPI surface (e.g. CancellationToken or [FromServices] parameters) is no longer applied to the request body description.

Fixes #64534
Fixes #64521
Fixes #67076

Copilot

Pull request overview

This pull request adds support for respecting IModelNameProvider attributes (like FromQuery(Name = "...")) when matching OpenAPI operation parameters with .NET action parameters for XML comment documentation. This ensures that XML documentation comments are correctly applied to parameters that have custom names specified via model binding attributes.

Key Changes:

Introduces a new GetOperationParameter helper method that considers both the parameter's original name and any custom names from IModelNameProvider attributes
Adds early null check for parameterInfo before attempting to match operation parameters
Updates generated code across all snapshot test files to include the new logic

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

File	Description
src/OpenApi/gen/XmlCommentGenerator.cs	Adds `System.Reflection` using statement for `ParameterInfo` type
src/OpenApi/gen/XmlCommentGenerator.Emitter.cs	Implements the core logic for parameter matching with `IModelNameProvider` support; adds `GetOperationParameter` helper method and includes `Microsoft.AspNetCore.Mvc.ModelBinding` namespace
src/OpenApi/test/.../snapshots/*.verified.cs	Updates all snapshot test files to reflect the generated code changes from the source generator

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

khellang · 2025-11-26T11:45:53Z

                            var requestBody = operation.RequestBody;
                            if (requestBody is not null)
                            {
                                requestBody.Description = parameterComment.Description;


@captainsafia Do you know why this fallback exists? We're seeing the CancellationToken argument being applied to the request body because of this, which is weird 🤔

Added a check to skip CancellationToken to avoid applying its XML doc to the request body. I can't see a scenario where you'd ever want to include a cancellation token in your OpenAPI docs 😅

Ideally, instead of checking against typeof(CancellationToken) directly, it should probably check against the binding source to see if it's BindingSource.Body instead of just blindly falling back to setting the request body description.

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

BrennanConroy

Could you file a follow-up issue to look at other parameter types besides CancellationToken? e.g. HttpContext, [FromServices], ClaimsPrincipal, etc.

Might want to look at the ApiParameterDescription.BindingSource?

khellang · 2026-06-08T11:25:51Z

Thanks @BrennanConroy! Filed #67076. Can probably take a stab at fixing it as well if no one beats me to it.

BrennanConroy · 2026-06-10T22:05:12Z

/azp run

azure-pipelines · 2026-06-10T22:05:29Z

Azure Pipelines successfully started running 2 pipeline(s).

BrennanConroy · 2026-06-11T02:48:20Z

The 2 new tests in src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.Controllers.cs failed. I think the verified file(s) need to be regenerated.

…eter is bound to it This avoids applying documentation for parameters that aren't part of the OpenAPI surface, like CancellationToken or [FromServices] parameters, to the request body description.

khellang · 2026-06-11T09:02:59Z

Rebased and updated the stale snapshots. I also included a commit that checks the BindingSource instead of the hard-coded CancellationToken check. It should fix #67076 as well.

BrennanConroy · 2026-06-11T23:32:48Z

                    {
                        var parameterInfo = methodInfo.GetParameters().SingleOrDefault(info => info.Name == parameterComment.Name);
-                        var operationParameter = operation.Parameters?.SingleOrDefault(parameter => parameter.Name == parameterComment.Name);
+                        var operationParameter = GetOperationParameter(operation, parameterInfo, parameterComment);


Not sure we care too much, but if it's easy to fix could we avoid calling GetModelNames multiple times per parameter?

BrennanConroy · 2026-06-11T23:34:46Z

+
+            foreach (var parameterDescription in context.Description.ParameterDescriptions)
+            {
+                if (parameterDescription.Source == BindingSource.Body


This excludes IFormFile (and other form types) from the description. Should those be excluded?

But those are bound to the body, right?

Right, so if there is a description on the form param it should end up as the description in openapi?
#67078 calls this out as well.

BrennanConroy · 2026-06-11T23:36:25Z

+                    if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment))
                    {
-                        var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name);
+                        var parameter = GetOperationParameter(operation, propertyInfo);


Do we need to apply IsRequestBodyParameter to this piece of code as well?

Copilot AI review requested due to automatic review settings November 26, 2025 08:45

khellang requested review from a team and captainsafia as code owners November 26, 2025 08:45

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 Nov 26, 2025

dotnet-policy-service Bot added the community-contribution Indicates that the PR has been added by a community member label Nov 26, 2025

Copilot started reviewing on behalf of khellang November 26, 2025 08:46 View session

Copilot finished reviewing on behalf of khellang November 26, 2025 08:49

Copilot AI reviewed Nov 26, 2025

View reviewed changes

Comment thread src/OpenApi/gen/XmlCommentGenerator.Emitter.cs Outdated

martincostello added area-mvc Includes: MVC, Actions and Controllers, Localization, CORS, most templates feature-openapi and removed needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically labels Nov 26, 2025

khellang force-pushed the fix/openapi-name-provider branch 3 times, most recently from 68d5b6f to 16a616e Compare November 26, 2025 09:27

khellang requested a review from Copilot November 26, 2025 09:27

Copilot started reviewing on behalf of khellang November 26, 2025 09:27 View session

Copilot finished reviewing on behalf of khellang November 26, 2025 09:30

Copilot AI reviewed Nov 26, 2025

View reviewed changes

Comment thread src/OpenApi/gen/XmlCommentGenerator.Emitter.cs Outdated

khellang force-pushed the fix/openapi-name-provider branch from 16a616e to d6a6aaa Compare November 26, 2025 10:11

khellang requested a review from Copilot November 26, 2025 11:13

Copilot started reviewing on behalf of khellang November 26, 2025 11:14 View session

Copilot finished reviewing on behalf of khellang November 26, 2025 11:15

Copilot AI reviewed Nov 26, 2025

View reviewed changes

Comment thread src/OpenApi/gen/XmlCommentGenerator.Emitter.cs Outdated

Comment thread src/OpenApi/gen/XmlCommentGenerator.Emitter.cs

Comment thread src/OpenApi/gen/XmlCommentGenerator.Emitter.cs Outdated

khellang requested a review from Copilot November 26, 2025 11:40

Copilot started reviewing on behalf of khellang November 26, 2025 11:40 View session

Copilot finished reviewing on behalf of khellang November 26, 2025 11:42

khellang commented Nov 26, 2025

View reviewed changes

Copilot AI reviewed Nov 26, 2025

View reviewed changes

Comment thread ...enApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/OperationTests.Controllers.cs Outdated

khellang mentioned this pull request Nov 26, 2025

Open API documentation is not generated from XML comments with header parameters #64521

Open

1 task

build-analysis Bot mentioned this pull request Nov 26, 2025

Known Build Error: error : Cannot create a file when that file already exists. #61178

Open

BrennanConroy approved these changes Jun 5, 2026

View reviewed changes

khellang mentioned this pull request Jun 8, 2026

Check BindingSource when emitting OpenAPI spec for parameters #67076

Open

khellang force-pushed the fix/openapi-name-provider branch from ea84636 to 7e1a640 Compare June 8, 2026 11:26

khellang mentioned this pull request Jun 8, 2026

OpenAPI XML comments: verify parameter binding-source handling for non-body parameter types #67078

Closed

3 tasks

Youssef1313 modified the milestones: 11.0-preview5, 11.0-preview6 Jun 10, 2026

khellang and others added 14 commits June 11, 2026 09:28

Add test demonstrating the issue

d841c03

Respect IModelNameProvider when matching OpenAPI parameters

081f929

Extract helper method to get model names

a01cb32

Also respect IModelNameProvider when getting XML docs for properties

a0baeb0

Fix nullability warnings from Copilot

64f6a13

Add test to verify cancellation token description

2b8a5b7

Don't include CancellationToken when applying XML doc description

e2e7ed5

Remove unused usings

8c957e3

Make assert less specific to avoid regressions

e276952

Add test for Minimal APIs

2d1979f

Don't fetch model names if there are no parameters

0c41448

Add back missing parameter and fix support for missing parameters

23c4a92

Update stale snapshots after rebase

3f30094

Only apply parameter documentation to the request body when the param…

d97acbe

…eter is bound to it This avoids applying documentation for parameters that aren't part of the OpenAPI surface, like CancellationToken or [FromServices] parameters, to the request body description.

khellang force-pushed the fix/openapi-name-provider branch from 7e1a640 to d97acbe Compare June 11, 2026 08:08

BrennanConroy reviewed Jun 11, 2026

View reviewed changes

Conversation

khellang commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

khellang Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

khellang Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

khellang Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

BrennanConroy left a comment

Choose a reason for hiding this comment

Uh oh!

khellang commented Jun 8, 2026

Uh oh!

BrennanConroy commented Jun 10, 2026

Uh oh!

azure-pipelines Bot commented Jun 10, 2026

Uh oh!

BrennanConroy commented Jun 11, 2026

Uh oh!

khellang commented Jun 11, 2026

Uh oh!

BrennanConroy Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

BrennanConroy Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

khellang Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

BrennanConroy Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

BrennanConroy Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

khellang commented Nov 26, 2025 •

edited

Loading

khellang Nov 26, 2025 •

edited

Loading