使用自定义MapGet扩展方法时Minimal API端点未出现在OpenAPI文档中的问题排查

看起来你遇到的问题很典型：通过自定义MapGet扩展注册的端点能正常访问，但完全没出现在OpenAPI的JSON文档里。我帮你梳理几个可能的原因和对应的解决方案：

1. 自定义MapGet的返回值切断了路由配置链路 #

你的自定义MapGet扩展最后返回的是IEndpointRouteBuilder（传入的builder参数），而不是builder.MapGet(...)返回的RouteHandlerBuilder。虽然这不会导致路由失效（毕竟端点能正常工作），但这种写法可能让OpenAPI元数据没有被正确附加到路由的最终配置中——WithName()和WithOpenApi()是对RouteHandlerBuilder的配置，但你没有把配置后的实例返回，而是返回了原始的builder，可能导致元数据丢失。

修改成和官方MapGet一致的返回值类型即可：

public static RouteHandlerBuilder MapGet(this IEndpointRouteBuilder builder, Delegate handler, [StringSyntax("Route")] string pattern = "")
{
    Guard.Against.AnonymousMethod(handler);
    // 返回配置后的RouteHandlerBuilder而非原始builder
    return builder.MapGet(pattern, handler)
        .WithName(handler.Method.Name)
        .WithOpenApi();
}

这种写法符合Minimal API的链式调用习惯，也能确保所有路由配置（包括OpenAPI元数据）都正确关联到对应端点。

2. 重复调用.WithOpenApi()导致元数据冲突 #

你的MapGroup方法已经对整个路由组调用了.WithOpenApi()，这会自动为组内所有端点启用OpenAPI支持。而在自定义MapGet中又再次调用.WithOpenApi()，重复配置可能导致OpenAPI生成器无法正确识别端点元数据。

解决方案是只保留一处.WithOpenApi()调用：

• 推荐保留路由组的.WithOpenApi()（组内所有端点会自动生效，无需单独配置）
• 移除自定义MapGet中的.WithOpenApi()调用

3. 空路由模板的潜在识别偏差 #

你的自定义MapGet用空字符串作为pattern的默认值，调用.MapGet(GetWeatherForecasts)时，实际路由模板是空字符串，结合组路径/api/WeatherForecasts，最终路由是/api/WeatherForecasts。虽然路由能正常访问，但内置OpenAPI生成器偶尔会对空模板的路由存在识别偏差。

可以尝试显式指定空模板验证：

public override void Map(WebApplication app)
{
    app.MapGroup(this)
        // 显式传递空字符串作为路由模板
        .MapGet("", GetWeatherForecasts);
}

如果显式传递后端点出现在OpenAPI里，说明默认值的处理存在细微的识别问题（语法合法但生成器未兼容）。

快速验证方案 #

你可以先尝试最核心的两个修改：把自定义MapGet的返回值改成RouteHandlerBuilder，并移除自定义MapGet中的.WithOpenApi()调用。这两个修改应该能解决大部分类似问题。如果还是不行，跳过反射逻辑手动注册一个端点组，看看是否出现在OpenAPI里——如果手动注册正常，说明反射逻辑没问题，问题还是出在自定义扩展的配置上。

内容来源于stack exchange