Repository navigation
Description
Is there an existing issue for this?
- I have searched the existing issues
Describe the bug
When generating an OpenAPI document, the wrong XML comments are sometimes used for descriptions. In particular, the description of a requestBody pulls the XML comment for the wrong function parameter; it seems to use the last parameter, rather than the parameter tagged with [FromBody] (which the documentation says to use).
Expected Behavior
The XML comment for the parameter identified as the request body is used as the description.
Steps To Reproduce
Repository: https://github.com/dosolkowski-work/aspnetcore-openapi-comments
If you look at aspnetcore-openapi-comments.json line 33, you can see the description is "Injected cancellation token.", but in the code the comment for that parameter is "Sample data provided by the user." It does get the data type correct, so it at least partially knows what the right parameter is.
Exceptions (if any)
No errors are thrown.
.NET Version
10.0.201
Anything else?
This happens just from the command line. Output of dotnet --info:
.NET SDK:
Version: 10.0.201
Commit: 4d3023de60
Workload version: 10.0.201
MSBuild version: 18.3.0-release-26153-122+4d3023de6
Runtime Environment:
OS Name: Windows
OS Version: 10.0.22631
OS Platform: Windows
RID: win-x64
Base Path: C:\Program Files\dotnet\sdk\10.0.201\
.NET workloads installed:
[wasm-tools]
Installation Source: SDK 10.0.200, VS 18.4.11605.240
Manifest Version: 10.0.105/10.0.100
Manifest Path: C:\Program Files\dotnet\sdk-manifests\10.0.100\microsoft.net.workload.mono.toolchain.current\10.0.105\WorkloadManifest.json
Install Type: Msi
[wasm-tools-net8]
Installation Source: SDK 10.0.200, VS 18.4.11605.240
Manifest Version: 10.0.105/10.0.100
Manifest Path: C:\Program Files\dotnet\sdk-manifests\10.0.100\microsoft.net.workload.mono.toolchain.net8\10.0.105\WorkloadManifest.json
Install Type: Msi
[wasm-tools-net9]
Installation Source: SDK 10.0.200, VS 18.4.11605.240
Manifest Version: 10.0.105/10.0.100
Manifest Path: C:\Program Files\dotnet\sdk-manifests\10.0.100\microsoft.net.workload.mono.toolchain.net9\10.0.105\WorkloadManifest.json
Install Type: Msi
Configured to use workload sets when installing new manifests.
Host:
Version: 10.0.5
Architecture: x64
Commit: a612c2a105
.NET SDKs installed:
10.0.200 [C:\Program Files\dotnet\sdk]
10.0.201 [C:\Program Files\dotnet\sdk]
.NET runtimes installed:
Microsoft.AspNetCore.App 8.0.25 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 9.0.14 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 10.0.4 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 10.0.5 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.NETCore.App 8.0.25 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 9.0.14 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 10.0.4 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 10.0.5 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.WindowsDesktop.App 8.0.25 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 9.0.14 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 10.0.4 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Microsoft.WindowsDesktop.App 10.0.5 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
Other architectures found:
x86 [C:\Program Files (x86)\dotnet]
registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]
Environment variables:
Not set
global.json file:
Not found
Activity
github-actions commentedon Mar 17, 2026
Triage Summary
Area:
area-minimal— The issue involves OpenAPI document generation (src/OpenApi/), which falls under the Minimal APIs area. The bug specifically affects how XML doc comments are mapped torequestBodydescriptions in generated OpenAPI documents.Type:
bug— The report clearly identifies incorrect behavior: when generating an OpenAPI document, thedescriptionof arequestBodyis populated with the XML comment of the last route handler parameter (e.g.,CancellationToken) instead of the XML comment of the parameter annotated with[FromBody]. The data type is resolved correctly, so the parameter identification partially works — only the description lookup is wrong.Potential Duplicates
Notes
[FromBody]parameters in OpenAPI document generation.(param)tags against the actual handler parameters when selecting which comment to use for the request body description.Warning
The following domains were blocked by the firewall during workflow execution:
learn.microsoft.compkgs.dev.azure.comTo allow these domains, add them to the
network.allowedlist in your workflow frontmatter:See Network Configuration for more information.
test: add regression test for OpenAPI request body comment bug (issue d…
fix: OpenAPI request body description uses correct parameter comment …
fix: OpenAPI request body description uses correct parameter comment …
fix: OpenAPI request body description uses correct parameter comment …
vfofanov commentedon Oct 15, 2026
Could #64535 be backported to
release/10.0? This still reproduces withMicrosoft.AspNetCore.OpenApi10.0.13 (SDK 10.0.402), and since 10.0 is the LTS line, many services will stay on it well after 11.0 ships.Our case. We build a shared hosting library that several ASP.NET Core services use to publish their OpenAPI documents. The services enable the XML comment generator (
GenerateDocumentationFile=true,AddOpenApi("v1")with a literal name), and almost every write endpoint takes a body plus something that is not part of the OpenAPI surface: a[FromServices]dependency, aCancellationToken,HttpContext, or a type bound through a staticBindAsync. Each of those has a<param>comment, because the services document every parameter. The generator then writes the last unmatched<param>torequestBody.description, so the published contract describes a request body as "The cancellation token." or "The clock.".Observed on 10.0.13, minimal API and controller action alike:
requestBody.description[FromServices] TimeProvider clockThe clock.TimeProvider clock(implicit service)The clock.Tenant tenant(staticBindAsync)The tenant.HttpContext contextThe context.CancellationToken cancellationTokenThe token.[FromQuery]/[FromHeader]The widget to create.(correct)Parameter order in the signature does not matter. Putting the body's
<param>last in the XML comment hides the bug; with no<param>on the body, a non-body comment still lands there.The cause is the fallback in
XmlCommentGenerator.Emitter.csL403-L408 at v10.0.13: any parameter that does not match an operation parameter is written tooperation.RequestBody.mainguards it withIsRequestBodyParameter(#64535).Workaround we ship meanwhile. An
IOpenApiOperationTransformer, registered after the generator's, finds the body parameter on the action, setsrequestBody.descriptionfrom that parameter's own<param>, and, when the body has none, clears a description that matches another parameter's<param>. It works, but every consumer of the generator has to rediscover the bug to know they need it, and the documents are wrong until they do.Minimal repro (
dotnet run, thenGET /openapi/v1.json):Both operations come out with
"requestBody": { "description": "The clock.", ... }; expectedThe widget to create..docs(api): document the endpoints for OpenAPI (#21)