如何通过RouteHandlerBuilder为Minimal API查询参数添加正确的OpenAPI文档？

你的问题核心在于Minimal API会自动根据方法参数生成对应的OpenAPI参数，而你通过operation.Parameters.Add()手动添加了同名参数，导致重复出现；同时自动生成的参数未携带自定义描述，最终呈现出两个无描述的重复参数。

方案一：修改自动生成的参数（推荐） #

无需新增参数，直接找到框架自动生成的osbToken参数并修改其属性：

group
    .MapGet(
        "/paymentCard",
        async (
            string osbToken,
            [FromServices] IDataversePaymentCardService paymentCardService
        ) =>
        {
            // 业务逻辑
            return Results.Ok();
        }
    )
    .Produces<PaymentCard?>(StatusCodes.Status200OK)
    .WithCommonErrorResponses()
    .WithSummary("Find a payment card based on osbToken (XYZ handle)")
    .WithOpenApi(static operation =>
    {
        // 定位自动生成的osbToken参数
        var osbTokenParam = operation.Parameters.FirstOrDefault(p => p.Name == "osbToken");
        if (osbTokenParam != null)
        {
            osbTokenParam.Description = "The handle from XYZ, which must start with 'ca_'";
            osbTokenParam.Required = true;
            // 可选：添加正则验证，强制参数以ca_开头
            osbTokenParam.Schema.Pattern = "^ca_.*";
        }
        return operation;
    });

方案二：直接通过特性标注（更简洁） #

如果不想在WithOpenApi中编写逻辑，可直接在方法参数上用特性标注，框架会自动读取这些信息生成正确的OpenAPI文档：

using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;

// ...

group
    .MapGet(
        "/paymentCard",
        async (
            [FromQuery, OpenApiParameter(
                Description = "The handle from XYZ, which must start with 'ca_'",
                Required = true,
                Schema = new OpenApiSchema { Type = "string", Pattern = "^ca_.*" }
            )] string osbToken,
            [FromServices] IDataversePaymentCardService paymentCardService
        ) =>
        {
            // 业务逻辑
            return Results.Ok();
        }
    )
    .Produces<PaymentCard?>(StatusCodes.Status200OK)
    .WithCommonErrorResponses()
    .WithSummary("Find a payment card based on osbToken (XYZ handle)");

两种方案都能让OpenAPI文档中只显示一个带有正确描述和规则的osbToken查询参数，解决重复问题。

内容的提问来源于stack exchange，提问作者Max