ASP.NET Core 8 Web API 版本控制配置

问题描述

在 ASP.NET Core 7 及更早版本中，API 版本控制通常通过 Microsoft.AspNetCore.Mvc.Versioning 和 Microsoft.AspNetCore.Mvc.ApiExplorer 包实现。但当升级到 .NET 8 时，这些包已被弃用，取而代之的是全新的 Asp.Versioning.Mvc 包。使用旧方法配置时：

services.AddApiVersioning();
services.AddVersionedApiExplorer(); // 此方法已不存在

会导致运行时错误：

无法解析 'Asp.Versioning.ApiExplorer.IApiVersionDescriptionProvider' 服务

这是因为新包的 API 配置方式发生了重大变化，需要采用不同的服务注册方法。

解决方案及步骤

步骤 1：安装必要的 NuGet 包

首先安装官方推荐的版本控制包：

Install-Package Asp.Versioning.Mvc
Install-Package Asp.Versioning.Mvc.ApiExplorer

步骤 2：配置服务

在 Program.cs 中更新服务注册逻辑：

builder.Services.AddEndpointsApiExplorer(); // 必需的基础服务
builder.Services.AddSwaggerGen();

// 配置 API 版本控制
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
})
.AddApiExplorer(options => 
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

关键变更：

• AddApiVersioning() 现在返回 IApiVersioningBuilder
• 通过链式调用 .AddApiExplorer() 注册版本探索器
• 不再需要单独的 AddVersionedApiExplorer() 方法

步骤 3：修复 Swagger 配置

修改 ConfigureSwaggerOptions 类以适配新服务：

// 使用新命名空间
using Asp.Versioning.ApiExplorer;

public class ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider)
    : IConfigureNamedOptions<SwaggerGenOptions>
{
    public void Configure(SwaggerGenOptions options)
    {
        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(
                description.GroupName,
                new OpenApiInfo
                {
                    Title = "Test API",
                    Version = description.ApiVersion.ToString()
                });
        }
    }

    public void Configure(string name, SwaggerGenOptions options) 
        => Configure(options);
}

在 Program.cs 中注册配置类：

builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();

最终版本显示效果

配置完成后，Swagger UI 将清晰展示各 API 版本：

要点说明

1. 服务注册顺序：
   AddApiExplorer() 必须链式调用在 AddApiVersioning() 之后，确保服务正确注入

2. 弃用处理：
   当 API 标记为弃用时，Swagger 会自动显示警告标识

   [ApiVersion("1.0", Deprecated = true)]

3. 路由配置：
   在控制器中使用属性路由时指定版本：

   [ApiVersion("2.0")]
   [Route("api/v{version:apiVersion}/[controller]")]
   public class ProductsController : ControllerBase { ... }

4. 多版本支持：
   单个控制器可同时支持多个版本：

   [ApiVersion("1.0")]
   [ApiVersion("2.0")]
   public class OrdersController : ControllerBase
   {
       [MapToApiVersion("2.0")]
       public ActionResult GetV2() { ... }
   }

最佳实践

建议将默认版本设置为 1.0，并通过 [ApiVersionNeutral] 特性标记不参与版本控制的 API（如健康检查端点）

总结

在 ASP.NET Core 8 中实现 API 版本控制，关键在于正确使用新版 Asp.Versioning.Mvc 包的链式注册模式。通过 AddApiVersioning().AddApiExplorer() 的组合调用，可无缝集成版本控制与 Swagger 文档生成，解决了旧版包弃用导致的兼容性问题。