ASP.NET Core中的API版本控制是什么？如何配置？

Microsoft.AspNetCore.Mvc.Versioning

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

Program.cs

Startup.cs

builder.Services

// Program.cs
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Versioning; // 引入版本控制命名空间
using Microsoft.AspNetCore.Mvc.ApiExplorer; // 引入API Explorer命名空间
using Microsoft.Extensions.Options;
using Swashbuckle.AspNetCore.SwaggerGen; // 引入Swagger命名空间
using Microsoft.OpenApi.Models; // 引入OpenAPI模型命名空间

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();

// 配置API版本控制
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true; // 在响应头中报告支持的API版本
    options.AssumeDefaultVersionWhenUnspecified = true; // 如果客户端未指定版本，则使用默认版本
    options.DefaultApiVersion = new ApiVersion(1, 0); // 设置默认API版本为1.0

    // 你可以选择不同的版本读取器，这里以Header为例
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
    // 或者 QueryStringApiVersionReader("api-version")
    // 或者 UrlSegmentApiVersionReader() - 需要配合路由模板
    // 或者 CombineApiVersionReader(new HeaderApiVersionReader("api-version"), new QueryStringApiVersionReader("api-version"))
});

// 配置API Explorer，用于与Swagger集成
builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV"; // 设置分组格式，如 "v1"
    options.SubstituteApiVersionInUrl = true; // 在URL中替换API版本占位符
});

// 配置Swagger生成器
builder.Services.AddSwaggerGen(options =>
{
    // 这里需要为每个API版本生成一个Swagger文档
    var provider = builder.Services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(description.GroupName, new OpenApiInfo()
        {
            Title = $"My API {description.ApiVersion}",
            Version = description.ApiVersion.ToString(),
            Description = description.IsDeprecated ? "此API版本已废弃。" : string.Empty
        });
    }
});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
        }
    });
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

[ApiVersion]

// Controllers/V1/WeatherForecastController.cs
using Microsoft.AspNetCore.Mvc;

namespace MyApi.Controllers.V1
{
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]")] // 注意这里的路由模板
    [ApiVersion("1.0")] // 标记这个控制器属于1.0版本
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecast")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}

// Controllers/V2/WeatherForecastController.cs
using Microsoft.AspNetCore.Mvc;

namespace MyApi.Controllers.V2
{
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiVersion("2.0")] // 标记这个控制器属于2.0版本
    public class WeatherForecastV2Controller : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Cooler", "Warmer", "Unpredictable" // 假设2.0版本有不同的摘要
        };

        private readonly ILogger<WeatherForecastV2Controller> _logger;

        public WeatherForecastV2Controller(ILogger<WeatherForecastV2Controller> logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecastV2")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 3).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-10, 40),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}

GET /api/weatherforecast

api-version: 1.0

api-version: 2.0

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

Program.cs