Skip to content

OpenAPI document generation uses wrong XML comments #65805

Closed

Description

@dosolkowski-work

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

  1. github-actions commented on Mar 17, 2026

    @github-actions
    Contributor

    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 to requestBody descriptions in generated OpenAPI documents.

    Type: bug — The report clearly identifies incorrect behavior: when generating an OpenAPI document, the description of a requestBody is 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

    • None found

    Notes

    • The reporter provides a reproducible repository with a concrete example showing the mismatch.
    • No regression information is provided — this may be a pre-existing bug in the XML comment resolution logic for [FromBody] parameters in OpenAPI document generation.
    • The root cause is likely in how the OpenAPI transformer resolves XML (param) tags against the actual handler parameters when selecting which comment to use for the request body description.

    Generated by Issue Triage Agent for dotnet/aspnetcore for issue #65805 · ◷

    Warning

    ⚠️ Firewall blocked 2 domains

    The following domains were blocked by the firewall during workflow execution:

    • learn.microsoft.com
    • pkgs.dev.azure.com

    To allow these domains, add them to the network.allowed list in your workflow frontmatter:

    network:
      allowed:
        - defaults
        - "learn.microsoft.com"
        - "pkgs.dev.azure.com"

    See Network Configuration for more information.

  2. added
    area-minimalIncludes minimal APIs, endpoint filters, parameter binding, request delegate generator etc
    bugThis issue describes a behavior which is not expected - a bug.
    on Mar 17, 2026
  3. added theissue type on May 1, 2026
  4. added this to the .NET 11 Planning milestone on Jul 1, 2026
  5. self-assigned this
    on Jul 1, 2026
  6. vfofanov commented on Oct 15, 2026

    @vfofanov

    Could #64535 be backported to release/10.0? This still reproduces with Microsoft.AspNetCore.OpenApi 10.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, a CancellationToken, HttpContext, or a type bound through a static BindAsync. Each of those has a <param> comment, because the services document every parameter. The generator then writes the last unmatched <param> to requestBody.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:

    Second parameter requestBody.description
    [FromServices] TimeProvider clock The clock.
    TimeProvider clock (implicit service) The clock.
    Tenant tenant (static BindAsync) The tenant.
    HttpContext context The context.
    CancellationToken cancellationToken The 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.cs L403-L408 at v10.0.13: any parameter that does not match an operation parameter is written to operation.RequestBody. main guards it with IsRequestBodyParameter (#64535).

    Workaround we ship meanwhile. An IOpenApiOperationTransformer, registered after the generator's, finds the body parameter on the action, sets requestBody.description from 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, then GET /openapi/v1.json):

    <Project Sdk="Microsoft.NET.Sdk.Web">
      <PropertyGroup>
        <TargetFramework>net10.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
        <GenerateDocumentationFile>true</GenerateDocumentationFile>
        <NoWarn>$(NoWarn);CS1591</NoWarn>
        <InterceptorsNamespaces>$(InterceptorsNamespaces);Microsoft.AspNetCore.OpenApi.Generated</InterceptorsNamespaces>
      </PropertyGroup>
      <ItemGroup>
        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.13" />
      </ItemGroup>
    </Project>
    using Microsoft.AspNetCore.Mvc;
    
    var builder = WebApplication.CreateBuilder(args);
    builder.Services.AddControllers();
    builder.Services.AddSingleton(TimeProvider.System);
    builder.Services.AddOpenApi("v1");
    
    var app = builder.Build();
    app.MapOpenApi();
    app.MapControllers();
    app.MapPost("/minimal/widgets", Endpoints.CreateWidget);
    app.Run();
    
    public record CreateWidgetRequest(string Name);
    
    public static class Endpoints
    {
        /// <summary>Creates a widget (minimal API).</summary>
        /// <param name="request">The widget to create.</param>
        /// <param name="clock">The clock.</param>
        public static IResult CreateWidget([FromBody] CreateWidgetRequest request, [FromServices] TimeProvider clock)
            => Results.Ok(request.Name);
    }
    
    [ApiController]
    [Route("controller/widgets")]
    public class WidgetsController : ControllerBase
    {
        /// <summary>Creates a widget (controller).</summary>
        /// <param name="request">The widget to create.</param>
        /// <param name="clock">The clock.</param>
        [HttpPost]
        public IActionResult Create([FromBody] CreateWidgetRequest request, [FromServices] TimeProvider clock)
            => Ok(request.Name);
    }

    Both operations come out with "requestBody": { "description": "The clock.", ... }; expected The widget to create..

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

Metadata

Metadata

Assignees

Labels

area-minimalIncludes minimal APIs, endpoint filters, parameter binding, request delegate generator etcbugThis issue describes a behavior which is not expected - a bug.feature-openapi

Type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions