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:
cc related: #64535, #67076
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 inXmlCommentGenerator.Emitter.cshad a narrow workaround that skipped onlytypeof(CancellationToken); it now uses a newIsRequestBodyParameterhelper that checksApiParameterDescription.Source == BindingSource.Body:That PR added negative tests for
CancellationTokenand[FromServices](documentation for these parameters must not leak ontoRequestBody.Description).Follow-up
Now that the matching is keyed off
ApiParameterDescription.Source/BindingSourceinstead 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 throughApiExplorer:HttpContext,HttpRequest,HttpResponseClaimsPrincipal[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 /IModelNameProviderConcrete asks:
HttpContext,ClaimsPrincipal, and keyed services (controllers and Minimal APIs).ApiParameterDescription.Sourceis the right discriminator for every case above (e.g.BindingSource.Special,BindingSource.Services,BindingSource.FormFile,BindingSource.Form) and tightenIsRequestBodyParameterif any of them need explicit handling.cc related: #64535, #67076