ASP.NET Boilerplate Web API版本控制问题：Swagger各版本显示全部API

你已经搭好了Swagger的多版本文档框架，但核心问题出在没正确实现DocInclusionPredicate的版本过滤逻辑——这个委托负责判断某个API是否应该出现在当前选中的Swagger文档里。下面是完整的解决方案，一步步帮你搞定：

1. 先配置API版本控制基础服务 #

在ConfigureServices里先注册API版本控制相关服务，这是Swagger版本筛选的前提：

services.AddApiVersioning(options =>
{
    // 允许在响应头返回API版本信息，方便调试
    options.ReportApiVersions = true;
    // 请求未指定版本时，默认使用v1.0（可根据需求调整）
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
});

// 注册版本化API探索器，给Swagger提供版本元数据
services.AddVersionedApiExplorer(options =>
{
    // 版本格式统一为"v1.0"这种形式
    options.GroupNameFormat = "'v'VVV";
    // 支持在URL中替换版本号
    options.SubstituteApiVersionInUrl = true;
});

2. 完善SwaggerGen的核心配置（重点实现版本过滤） #

替换你现有的AddSwaggerGen代码，用API探索器自动生成版本文档，并正确实现DocInclusionPredicate：

services.AddSwaggerGen(options =>
{
    // 从API版本探索器中自动获取所有版本，生成对应Swagger文档
    var apiVersionProvider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
    foreach (var versionDesc in apiVersionProvider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(versionDesc.GroupName, new Info
        {
            Title = "My API",
            Version = versionDesc.ApiVersion.ToString()
        });
    }

    // 关键：实现文档包含规则，只显示对应版本的API
    options.DocInclusionPredicate((docName, apiDesc) =>
    {
        // 从API元数据中提取标注的版本信息
        var apiVersions = apiDesc.ActionDescriptor.EndpointMetadata
            .OfType<ApiVersionAttribute>()
            .SelectMany(attr => attr.Versions);

        // 如果API没标注版本，默认归到v1.0（可根据你的业务调整）
        if (!apiVersions.Any())
        {
            return docName == "v1.0";
        }

        // 检查当前Swagger文档版本是否在API的允许版本列表中
        return apiVersions.Any(v => $"v{v.ToString()}" == docName);
    });
});

3. 给API控制器/方法标注对应版本 #

最后要在你的API上明确标注版本，Swagger才能正确识别并过滤：

示例1：不同控制器对应不同版本 #

// V1版本产品控制器
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV1Controller : AbpController
{
    [HttpGet]
    public IActionResult GetAll()
    {
        return Ok("这是V1版本的产品查询接口");
    }
}

// V2版本产品控制器
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : AbpController
{
    [HttpGet]
    public IActionResult GetAll()
    {
        return Ok("这是V2版本的产品查询接口");
    }
}

示例2：同一控制器内不同方法对应不同版本 #

[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : AbpController
{
    // 属于V1版本的接口
    [HttpGet]
    public IActionResult GetV1()
    {
        return Ok("V1版本的订单查询");
    }

    // 属于V2版本的接口
    [HttpGet]
    [MapToApiVersion("2.0")]
    public IActionResult GetV2()
    {
        return Ok("V2版本的订单查询");
    }
}

配置完成后重启项目，再打开Swagger就能看到每个版本下只显示对应标注的API了。

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