.NET 7.0 Minimal API中.WithOpenApi()导致Swagger参数文档丢失问题

1. 保留.WithOpenApi()同时显示参数文档的方法 #

当调用.WithOpenApi()时，默认会生成全新的OpenApiOperation实例，覆盖掉框架自动推断的参数描述等元数据。要保留参数描述，有两种可行方案：

方案一：在.WithOpenApi()委托中手动合并原有参数描述 #

在配置端点时，通过.WithOpenApi()的委托参数，从API描述中获取原始参数描述并赋值给生成的OpenApiOperation：

app.MapGet("/api/test", MyHandler)
   .WithOpenApi(operation => {
       // 获取当前端点的API描述
       var apiDescription = app.Services.GetRequiredService<IApiDescriptionGroupCollectionProvider>()
           .ApiDescriptionGroups.Items
           .SelectMany(group => group.Items)
           .FirstOrDefault(desc => desc.RelativePath == "/api/test");
       
       if (apiDescription != null)
       {
           // 遍历参数，补全描述
           foreach (var param in operation.Parameters)
           {
               var originalParam = apiDescription.ParameterDescriptions
                   .FirstOrDefault(p => p.Name == param.Name);
               if (originalParam != null && !string.IsNullOrEmpty(originalParam.Description))
               {
                   param.Description = originalParam.Description;
               }
           }
       }
       return operation;
   });

方案二：自定义操作过滤器全局处理 #

创建一个IOperationFilter实现类，自动为所有操作补全参数描述，无需逐个端点配置：

public class PreserveParameterDescriptionFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        foreach (var param in operation.Parameters)
        {
            var apiParam = context.ApiDescription.ParameterDescriptions
                .FirstOrDefault(p => p.Name == param.Name);
            if (apiParam != null && !string.IsNullOrEmpty(apiParam.Description))
            {
                param.Description = apiParam.Description;
            }
        }
    }
}

然后在注册SwaggerGen时添加该过滤器：

builder.Services.AddSwaggerGen(options =>
{
    options.OperationFilter<PreserveParameterDescriptionFilter>();
});

2. 问题归属与是否需要提交修复 #

这个问题属于Swashbuckle.AspNetCore的设计细节问题：.WithOpenApi()的默认逻辑是创建全新的OpenApiOperation，而非基于框架自动生成的API元数据进行增量修改，导致原有参数描述丢失。

如果希望优化这个体验，建议向Swashbuckle.AspNetCore的代码仓库提交Issue，提议修改.WithOpenApi()的默认行为，或者提供更便捷的API来合并原有元数据，避免开发者手动处理。

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