Skip to content

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

Description

@khellang

Background

In #64535 (fixing #67076) the XML comment operation transformer was changed so that <param> documentation only falls back to the request body when the parameter is actually bound to the body. The old code in XmlCommentGenerator.Emitter.cs had a narrow workaround that skipped only typeof(CancellationToken); it now uses a new IsRequestBodyParameter helper that checks ApiParameterDescription.Source == BindingSource.Body:

private static bool IsRequestBodyParameter(OpenApiOperationTransformerContext context, ParameterInfo? parameterInfo, XmlParameterComment comment)
{
    var modelNames = GetModelNames(parameterInfo, parameterInfo?.Name ?? comment.Name);

    foreach (var parameterDescription in context.Description.ParameterDescriptions)
    {
        if (parameterDescription.Source == BindingSource.Body
            && parameterDescription.Name is { } parameterName
            && modelNames.Contains(parameterName))
        {
            return true;
        }
    }

    return false;
}

That PR added negative tests for CancellationToken and [FromServices] (documentation for these parameters must not leak onto RequestBody.Description).

Follow-up

Now that the matching is keyed off ApiParameterDescription.Source/BindingSource instead of a hard-coded type check, we should systematically confirm and lock in the behavior for the rest of the special / non-body parameter types, since each takes a different binding path through ApiExplorer:

  • HttpContext, HttpRequest, HttpResponse
  • ClaimsPrincipal
  • [FromKeyedServices]
  • IFormFile / IFormFileCollection / [FromForm] — these do relate to the request body/form, so the description should land on the right place (form content), not be dropped
  • [FromBody] parameters with custom names / IModelNameProvider

Concrete asks:

  • Add negative tests for HttpContext, ClaimsPrincipal, and keyed services (controllers and Minimal APIs).
  • Verify the positive case for form/file parameters still applies documentation correctly.
  • Confirm ApiParameterDescription.Source is the right discriminator for every case above (e.g. BindingSource.Special, BindingSource.Services, BindingSource.FormFile, BindingSource.Form) and tighten IsRequestBodyParameter if any of them need explicit handling.

cc related: #64535, #67076

Metadata

Metadata

Assignees

No one assigned

    Labels

    area-minimalIncludes minimal APIs, endpoint filters, parameter binding, request delegate generator etc

    Type

    No fields configured for Task.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions