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

前言

首先希望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

如果不指定版本路由那么定義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")]即可。

但是兩個相同的版本中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 };//如果相同版本信息路由下增加   
　　　　　　　　　　　[ApiExplorerSettings(GroupName = "v1")]進行區分即可 //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交互。