ASP.NET Core WebApi版本控制的實現

前言:

 在日常項目開發中,隨著項目需求不斷的累加、不斷的迭代;項目服務接口需要向下兼容歷史版本;前些時候就因為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/WebAPIVersionDemo

到此這篇關於ASP.NET Core WebApi版本控制的實現的文章就介紹到這瞭,更多相關ASP.NET Core WebApi版本控制內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet!

推薦閱讀: