NSwag可生成OpenAPI文档，Swashbuckle无法识别控制器问题

你遇到的Swashbuckle无法识别控制器的核心原因是：你使用了API版本控制（ApiVersion特性），但Swashbuckle默认没有和API版本探索器（IApiVersionDescriptionProvider）做集成，导致它无法扫描到带版本标记的控制器端点。NSwag因为默认对API版本控制的兼容性更好，所以能正常识别。

解决步骤： #

1. 确认安装正确的NuGet包
   确保项目已安装Asp.Versioning.Mvc.ApiExplorer（针对.NET 6+/7的API版本控制配套包，替代旧的Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer）。

2. 完善API版本控制配置
   在服务注册时，显式配置API版本控制并启用ApiExplorer的版本分组功能：

   builder.Services.AddApiVersioning(options =>
   {
       options.ReportApiVersions = true;
       options.AssumeDefaultVersionWhenUnspecified = true;
       options.DefaultApiVersion = new ApiVersion(1, 0);
   })
   .AddApiExplorer(options =>
   {
       // 定义版本分组格式，比如"v1"、"v2"
       options.GroupNameFormat = "'v'VVV";
       // 允许在URL中替换版本号，确保路由匹配
       options.SubstituteApiVersionInUrl = true;
   });
   

3. 配置SwaggerGen关联API版本探索器
   修改AddSwaggerGen的配置，让它从API版本探索器中获取版本信息，生成对应版本的Swagger文档：

   builder.Services.AddSwaggerGen(options =>
   {
       var apiVersionProvider = builder.Services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
       
       // 为每个API版本生成独立的Swagger文档
       foreach (var versionDesc in apiVersionProvider.ApiVersionDescriptions)
       {
           options.SwaggerDoc(versionDesc.GroupName, new OpenApiInfo
           {
               Title = "你的API标题",
               Version = versionDesc.ApiVersion.ToString(),
               Description = $"API版本 {versionDesc.ApiVersion}"
           });
       }
   });
   

4. 更新SwaggerUI中间件（可选但推荐）
   如果你需要在SwaggerUI中切换不同版本的API文档，修改中间件配置：

   app.UseSwagger();
   app.UseSwaggerUI(options =>
   {
       var apiVersionProvider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
       
       foreach (var versionDesc in apiVersionProvider.ApiVersionDescriptions)
       {
           options.SwaggerEndpoint($"/swagger/{versionDesc.GroupName}/swagger.json", versionDesc.GroupName.ToUpperInvariant());
       }
   });
   

完成以上配置后，重新启动项目，Swashbuckle就能正确识别带版本标记的控制器，生成包含paths和components的完整OpenAPI文档了。

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