ASP.NET Core WebApi版本控制

程序员文章站 2023-12-28 20:36:16

...

一、WebApi版本控制实现
　　通过Microsoft.AspNetCore.Mvc.Versioning 实现webapi 版本控制
创建WebApi项目，添加Nuget包：Microsoft.AspNetCore.Mvc.Versioning
Install-Package Microsoft.AspNetCore.Mvc.Versioning
修改项目Startup文件，使用Microsoft.AspNetCore.Mvc.Versioning
复制代码
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    //根据需要设置，以下内容
    services.AddApiVersioning(apiOtions =>
    {
        //返回响应标头中支持的版本信息
        apiOtions.ReportApiVersions = true;
        //此选项将用于不提供版本的请求。默认情况下, 假定的 API 版本为1.0
        apiOtions.AssumeDefaultVersionWhenUnspecified = true;
        //缺省api版本号，支持时间或数字版本号
        apiOtions.DefaultApiVersion = new ApiVersion(1, 0);
        //支持MediaType、Header、QueryString 设置版本号;缺省为QueryString、UrlSegment设置版本号;后面会详细说明对于作用
        apiOtions.ApiVersionReader = ApiVersionReader.Combine(
            new MediaTypeApiVersionReader("api-version"),
            new HeaderApiVersionReader("api-version"),
            new QueryStringApiVersionReader("api-version"),
            new UrlSegmentApiVersionReader());
    });
    services.AddControllers();
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseHttpsRedirection();

    //使用ApiVersioning
    app.UseApiVersioning();

    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

}
复制代码
WebApi设置版本：
　　a）通过ApiVersion标记指定指定控制器或方法的版本号；Url参数控制版本(QueryStringApiVersionReader)，如下：

复制代码
namespace WebAPIVersionDemo.Controllers
{
[ApiController]
[Route("[controller]")]
//Deprecated=true:表示v1即将弃用，响应头中返回
[ApiVersion(“1.0”, Deprecated = true)]
[ApiVersion(“2.0”)]public class WeatherForecastController : ControllerBase
{
private static readonly string[] Summaries = new[]{“Freezing”, “Bracing”, “Chilly”, “Cool”, “Mild”, “Warm”, “Balmy”, “Hot”, “Sweltering”, “Scorching”};

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

}
复制代码
　　通过参数api-version参数指定版本号；调用结果：

b）通过Url Path Segment控制版本号(UrlSegmentApiVersionReader)：为控制器添加路由方式如下，apiVersion为固定格式

[Route("/api/v{version:apiVersion}/[controller]")]
　　调用方式：通过调用路径传入版本号，如：http://localhost:5000/api/v1/weatherforecast

c）通过Header头控制版本号：在Startup中设置（HeaderApiVersionReader、MediaTypeApiVersionReader）

apiOtions.ApiVersionReader = ApiVersionReader.Combine(
new MediaTypeApiVersionReader(“api-version”),
new HeaderApiVersionReader(“api-version”));
　　调用方式，在请求头或中MediaType中传递api版本，如下：

其他说明：
　　　　a）ReportApiVersions设置为true时，返回当前支持版本号（api-supported-versions）；Deprecated 参数设置为true表示已弃用，在响应头中也有显示（api-deprecated-versions）：

b）MapToApiVersion标记：允许将单个 API 操作映射到任何版本（可以在v1的控制器中添加v3的方法）；在上面控制器中添加以下代码，访问v3版本方法

复制代码
[HttpGet]
[MapToApiVersion(“3.0”)]
public IEnumerable GetV3()
{
//获取版本
string v = HttpContext.GetRequestedApiVersion().ToString();
var rng = new Random();
return Enumerable.Range(1, 1).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = rng.Next(-20, 55),
Summary = $“v{v}:{Summaries[rng.Next(Summaries.Length)]}”
})
.ToArray();
}
复制代码

c）注意事项：

1、路径中参数版本高于，其他方式设置版本

2、多种方式传递版本，只能采用一种方式传递版本号

3、SwaggerUI中MapToApiVersion设置版本不会单独显示

二、Swagger UI中版本接入
　1、添加包：Swashbuckle.AspNetCore、Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

//swaggerui 包
Install-Package Swashbuckle.AspNetCore
//api版本
Install-Package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
　2、修改Startup代码：

复制代码
public class Startup
{
///
/// Api版本提者信息
///
private IApiVersionDescriptionProvider provider;

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
      
    //根据需要设置，以下内容
    services.AddApiVersioning(apiOtions =>
    {
        //返回响应标头中支持的版本信息
        apiOtions.ReportApiVersions = true;
        //此选项将用于不提供版本的请求。默认情况下, 假定的 API 版本为1.0
        apiOtions.AssumeDefaultVersionWhenUnspecified = true;
        //缺省api版本号，支持时间或数字版本号
        apiOtions.DefaultApiVersion = new ApiVersion(1, 0);
        //支持MediaType、Header、QueryString 设置版本号;缺省为QueryString设置版本号
        apiOtions.ApiVersionReader = ApiVersionReader.Combine(
                new MediaTypeApiVersionReader("api-version"),
                new HeaderApiVersionReader("api-version"),
                new QueryStringApiVersionReader("api-version"),
                new UrlSegmentApiVersionReader());
    });


    services.AddVersionedApiExplorer(option =>
    {
        option.GroupNameFormat = "接口：'v'VVV";
        option.AssumeDefaultVersionWhenUnspecified = true;
    });

    this.provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
    services.AddSwaggerGen(options =>
    {
        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(description.GroupName,
                    new Microsoft.OpenApi.Models.OpenApiInfo()
                    {
                        Title = $"接口 v{description.ApiVersion}",
                        Version = description.ApiVersion.ToString(),
                        Description = "切换版本请点右上角版本切换"
                    }
            );
        }
        options.IncludeXmlComments(this.GetType().Assembly.Location.Replace(".dll", ".xml"), true);
    });

}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    //……    

    //使用ApiVersioning
    app.UseApiVersioning();

    //启用swaggerui，绑定api版本信息
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        foreach (var description in provider.ApiVersionDescriptions)
        {
            c.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
        }
    });

    //……    
}

}
深圳网站建设www.sz886.com

ASP.NET Core WebApi版本控制