ASP.NET Core WebApi版本控制
阿新 • • 發佈：2021-02-21
前言：
在日常專案開發中，隨著專案需求不斷的累加、不斷的迭代；專案服務介面需要向下相容歷史版本；前些時候就因為Api介面為做版本管理導致介面對低版本相容處理不友好。
最近就像瞭解下如何實現WebApi版本控制，那麼版本控制有什麼好處呢？
WebApi版本控制的好處
- 有助於及時推出功能, 而不會破壞現有系統，相容性處理更友好。
- 它還可以幫助為選定的客戶提供額外的功能。
接下來就來實現版本控制以及在Swagger UI中接入WebApi版本
一、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<WeatherForecast> 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
{
/// <summary>
/// Api版本提者資訊
/// </summary>
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());
}
});
//……
}
}
3、執行效果：
其他：
示例地址：https://github.com/cwsheng/WebAPIVersion