net core webapi多版本控制與swagger（nswag）配置

王延領發表於2020-11-06
WebAPISwagger

前言

首先希望webapi 支援多版本，swagger針對不同的版本可進行互動。多版本控制基於Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 包，swagger可以選擇Swashbuckle.AspNetCore和nswag.AspNetCore.由於我們系統使用的是nswag所以繼續沿用，當然Swashbuckle.AspNetCore也和不錯，有時間再總結。

版本控制

1.匯入相關nuget。Swashbuckle.AspNetCore，nswag.AspNetCore.

2.新增api多版本控制服務 

2.1.首先是讓專案支援多版本的服務新增

  services.AddApiVersioning(option =>
                {
                    // 可選，為true時API返回支援的版本資訊
                    option.ReportApiVersions = true;
                    // 不提供版本時，預設為1.0
                    option.AssumeDefaultVersionWhenUnspecified = true;
                    //版本資訊放到header ,不寫在不配置路由的情況下，版本資訊放到response url 中
                    option.ApiVersionReader = new HeaderApiVersionReader("api-version");
                    // 請求中未指定版本時預設為1.0
                    option.DefaultApiVersion = new ApiVersion(1, 0);
                }).AddVersionedApiExplorer(option =>
                {          // 版本名的格式：v+版本號
                    option.GroupNameFormat = "'v'V";
                    option.AssumeDefaultVersionWhenUnspecified = true;
                });
                ////獲取webapi版本資訊，用於swagger多版本支援 
                this.provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();

服務我們已經注入了，下面我們看一下怎麼webapi 多版本的支援

2.1.1.多版本的控制

1.QueryString

  /// <summary>
    /// 使用者管理API
    /// </summary>
    [ServiceFilter(typeof(LogFilterAttribute))]
    [ApiController]
    [Route("api/[controller]/[action]")]
    [ApiVersion("2.0")]
   
    public class UserController : ApiController
    {}

當我們註冊服務時不加  option.ApiVersionReader = new HeaderApiVersionReader("api-version"); 那麼版本資訊就是通過url？api-version=2進行傳遞

2.header

net core webapi多版本控制與swagger（nswag）配置 
  /// <summary>
    /// 使用者管理API
    /// </summary>
    [ServiceFilter(typeof(LogFilterAttribute))]
    [ApiController]
    [Route("api/[controller]/[action]")]
    [ApiVersion("2.0")]
   
    public class UserController : ApiController
    {}
View Code

如果不指定版本路由那麼定義ApiVersionReader  則通過header傳遞

 

 

 

 以上兩種方式，預設版本（v1.0）均可不傳遞版本號

3.版本路由

 /// <summary>
    /// 使用者管理API
    /// </summary>
    [ServiceFilter(typeof(LogFilterAttribute))]
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]/[action]")]
    [Authorize]
    [ApiVersion("1.0")]
    [ApiVersion("2.0")]
    public class UserController : ApiController
    {}

這種方式很直觀，但如果原有專案沒有使用多版本控制不建議用，可採用header的方式更為合理一些，

 

 

2.1.2 同一個 Controller 支援多版本

增加多個  [ApiVersion("2.0")]即可。

net core webapi多版本控制與swagger（nswag）配置 
   /// <summary>
    /// 使用者管理API
    /// </summary>
    [ServiceFilter(typeof(LogFilterAttribute))]
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]/[action]")]
    //[Authorize]
    [ApiVersion("1.0")]
    [ApiVersion("2.0")]
    public class UserController : ApiController
    {}
View Code

但是兩個相同的版本中Controller不能有相同的方法。比如v1 資料夾和v2檔案的UserController都指向v2版本,是不能同時擁有GetList()的，但是如果我們想要v2中的GetList重寫v1的GetList方法，其他的方法都繼承過來怎麼處理呢？

v1 版本中的controller指定[ApiVersion("1.0")][ApiVersion("2.0")]

/// <summary>
    /// v1.使用者管理API
    /// </summary>
    [ServiceFilter(typeof(LogFilterAttribute))]
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]/[action]")]
    //[Authorize]
    [ApiVersion("1.0")]
    [ApiVersion("2.0")]
    public class UserController : ApiController
    {}

v2版本中的controller指定[ApiVersion("2.0")]

    /// <summary>
    /// v1.使用者管理API
    /// </summary>
    [ServiceFilter(typeof(LogFilterAttribute))]
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]/[action]")]
    //[Authorize]
    [ApiVersion("2.0")]
    public class UserController : ApiController
    {}

v1版本中的GetList（）方法 MapToApiVersion到v1即可

         /// <summary>
        /// 獲取使用者列表
        /// </summary>
        /// <returns></returns>
       [HttpGet,MapToApiVersion("1.0")]
        public NetResponse<List<User>> GetList()
        {}

這樣以來v1與v2中的GetList 就互不影響了。

3.註冊nswag（AddOpenApiDocument和AddSwaggerDocument）

NSwag注入服務有兩個方法：AddOpenApiDocument和AddSwaggerDocument，兩者的區別就是架構型別不一樣，AddOpenApiDocument的SchemaType使用的是OpenApi3，AddSwaggerDocument的SchemaType使用的是Swagger2：

我用的是AddSwaggerDocument

 foreach (var description in provider.ApiVersionDescriptions)
                {
                    services.AddSwaggerDocument(document =>
                {
                    document.OperationProcessors.Add(new OperationSecurityScopeProcessor("JWT token"));
                    document.DocumentName = description.GroupName;
                    document.Version = description.GroupName;
                    document.ApiGroupNames = new string[] { description.GroupName };
                    //jwt 認證
                    document.AddSecurity("JWT token", Enumerable.Empty<string>(),
                          new OpenApiSecurityScheme()
                          {
                              Type = OpenApiSecuritySchemeType.ApiKey,
                              Name = nameof(Authorization),
                              In = OpenApiSecurityApiKeyLocation.Header,
                              Description = "將token值複製到如下格式: \nBearer {token}"
                          }
                      );

                });
                }

4.nswag中介軟體 

                app.UseOpenApi();
                app.UseSwaggerUi3(setting =>
                {
                });

是的我們做任何配置，如果你願意其實有很多好玩的。但上面的配置方式足夠多版本的控制與nswag互動。

 

相關文章