為你的 ASP.NET Core API 加上版本吧 !!

Posted on 2018-12-21

是不是有對外服務的 API 沒有辦法改版,怕改了就會有問題而影響到使用者,如果可以控制 API 的版本就沒有這個問題了,來為你的 API 加上版本吧 !!

ASP.NET Core 2.1.5

安裝套件

設定

  • Startup 的 Services 裡面註冊使用 ApiVersioning
    • ReportApiVersions 指的是會在 Header 裡面列出目前有的 Version
    • AssumeDefaultVersionWhenUnspecified 指的是可以不傳 Version,就會使用預設的 Version,也就是 DefaultApiVersion 的設定
services.AddApiVersioning(o =>
{
    o.ReportApiVersions = true;
    o.AssumeDefaultVersionWhenUnspecified = true;
    o.DefaultApiVersion = new ApiVersion(1, 0);
});

預設 Version

  • 加入兩個 Controller,Value1ControllerValue2Controller,把 Route 設定成一樣都是 api/values
  • 在 Controller 上面加 ApiVersion attribute,指定每一個 Controller 的版本
[ApiVersion("1.0")]
[Route("api/values")]
public class Value1Controller : ControllerBase
{
    [HttpGet]
    public string Get()
    {
        return "Version1";
    }
}
[ApiVersion("2.0")]
[Route("api/values")]
public class Value2Controller : ControllerBase
{
    [HttpGet]
    public string Get()
    {
        return "Version2";
    }
}
  • 因為有預設值的設定,所以如果瀏覽 api/values 時,都會進到 Value1Controller 裡面

  • 因為有設定 ReportApiVersions,所以看 Response 的 Header 就會看到有 api-supported-versions

路由 Version

  • 修改 Value1ControllerValue2ControllerRoute 設定,把 Version 加入路由约束
[ApiVersion("1.0")]
[Route("api/{v:apiVersion}/values")]
public class Value1Controller : ControllerBase
{
}
[ApiVersion("2.0")]
[Route("api/{v:apiVersion}/values")]
public class Value2Controller : ControllerBase
{
}
  • 修改後原本的路由就沒有用了,需要多傳 Version,這樣子就可以作到控制版本了

淘汰 Version

  • 如果有舊的版本預計要淘汰的話,可以多加上 Deprecated 的設定
[ApiVersion("1.0", Deprecated = true)]
[Route("api/{v:apiVersion}/values")]
public class Value1Controller : ControllerBase
{
}
  • 這樣子不管是用 1.0 還是 2.0,都會出現 api-deprecated-versionsapi-supported-versions 跟你說目前的版本和要棄用的版本