首先希望webapi 支持多版本，swagger针对不同的版本可进行交互。多版本控制基于Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 包，swagger可以选择Swashbuckle.AspNetCore和nswag.AspNetCore.由于我们系统使用的是nswag所以继续沿用，当然Swashbuckle.AspNetCore也和不错，有时间再总结。

  1.   services.AddApiVersioning(option =>
  2.                 {
  3.                     // 可选，为true时API返回支持的版本信息
  4.                     option.ReportApiVersions = true;
  5.                     // 不提供版本时，默认为1.0
  6.                     option.AssumeDefaultVersionWhenUnspecified = true;
  7.                     //版本信息放到header ,不写在不配置路由的情况下，版本信息放到response url 中
  8.                     option.ApiVersionReader = new HeaderApiVersionReader("api-version");
  9.                     // 请求中未指定版本时默认为1.0
  10.                     option.DefaultApiVersion = new ApiVersion(1, 0);
  11.                 }).AddVersionedApiExplorer(option =>
  12.                 {          // 版本名的格式：v+版本号
  13.                     option.GroupNameFormat = "'v'V";
  14.                     option.AssumeDefaultVersionWhenUnspecified = true;
  15.                 });
  16.                 ////获取webapi版本信息，用于swagger多版本支持 
  17.                 this.provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
  18.

服务我们已经注入了，下面我们看一下怎么webapi 多版本的支持

1.QueryString

  1.   /// <summary>
  2.     /// 用户管理API
  3.     /// </summary>
  4.     [ServiceFilter(typeof(LogFilterAttribute))]
  5.     [ApiController]
  6.     [Route("api/[controller]/[action]")]
  7.     [ApiVersion("2.0")]
  8.    
  9.     public class UserController : ApiController
  10.     {}

当我们注册服务时不加  option.ApiVersionReader = new HeaderApiVersionReader(“api-version”); 那么版本信息就是通过url？api-version=2进行传递

2.header

View Code

如果不指定版本路由那么定义ApiVersionReader  则通过header传递

 

 

 

 以上两种方式，默认版本（v1.0）均可不传递版本号

3.版本路由

  1.  /// <summary>
  2.     /// 用户管理API
  3.     /// </summary>
  4.     [ServiceFilter(typeof(LogFilterAttribute))]
  5.     [ApiController]
  6.     [Route("api/v{version:apiVersion}/[controller]/[action]")]
  7.     [Authorize]
  8.     [ApiVersion("1.0")]
  9.     [ApiVersion("2.0")]
  10.     public class UserController : ApiController
  11.     {}

这种方式很直观，但如果原有项目没有使用多版本控制不建议用，可采用header的方式更为合理一些，

 

 

增加多个  [ApiVersion(“2.0”)]即可。

View Code

但是两个相同的版本中Controller不能有相同的方法。比如v1 文件夹和v2文件的UserController都指向v2版本,是不能同时拥有GetList()的，但是如果我们想要v2中的GetList重写v1的GetList方法，其他的方法都继承过来怎么处理呢？

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

  1. /// <summary>
  2.     /// v1.用户管理API
  3.     /// </summary>
  4.     [ServiceFilter(typeof(LogFilterAttribute))]
  5.     [ApiController]
  6.     [Route("api/v{version:apiVersion}/[controller]/[action]")]
  7.     //[Authorize]
  8.     [ApiVersion("1.0")]
  9.     [ApiVersion("2.0")]
  10.     public class UserController : ApiController
  11.     {}

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

  1.     /// <summary>
  2.     /// v1.用户管理API
  3.     /// </summary>
  4.     [ServiceFilter(typeof(LogFilterAttribute))]
  5.     [ApiController]
  6.     [Route("api/v{version:apiVersion}/[controller]/[action]")]
  7.     //[Authorize]
  8.     [ApiVersion("2.0")]
  9.     public class UserController : ApiController
  10.     {}

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

  1.          /// <summary>
  2.         /// 获取用户列表
  3.         /// </summary>
  4.         /// <returns></returns>
  5.        [HttpGet,MapToApiVersion("1.0")]
  6.         public NetResponse<List<User>> GetList()
  7.         {}

这样以来v1与v2中的GetList 就互不影响了。

NSwag注入服务有两个方法：AddOpenApiDocument和AddSwaggerDocument，两者的区别就是架构类型不一样，AddOpenApiDocument的SchemaType使用的是OpenApi3，AddSwaggerDocument的SchemaType使用的是Swagger2：

我用的是AddSwaggerDocument

  1.  foreach (var description in provider.ApiVersionDescriptions)
  2.                 {
  3.                     services.AddSwaggerDocument(document =>
  4.                 {
  5.                     document.OperationProcessors.Add(new OperationSecurityScopeProcessor("JWT token"));
  6.                     document.DocumentName = description.GroupName;
  7.                     document.Version = description.GroupName;
  8.                     document.ApiGroupNames = new string[] { description.GroupName };//如果相同版本信息路由下增加   
    　　　　　　　　　　　[ApiExplorerSettings(GroupName = "v1")]进行区分即可
  9.                     //jwt 认证
  10.                     document.AddSecurity("JWT token", Enumerable.Empty<string>(),
  11.                           new OpenApiSecurityScheme()
  12.                           {
  13.                               Type = OpenApiSecuritySchemeType.ApiKey,
  14.                               Name = nameof(Authorization),
  15.                               In = OpenApiSecurityApiKeyLocation.Header,
  16.                               Description = "将token值复制到如下格式: \nBearer {token}"
  17.                           }
  18.                       );
  20.                 });
  21.                 }
  1.                 app.UseOpenApi();
  2.                 app.UseSwaggerUi3(setting =>
  3.                 {
  4.                 });

是的我们做任何配置，如果你愿意其实有很多好玩的。但上面的配置方式足够多版本的控制与nswag交互。

 

版权声明：本文为wyl1924原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://www.cnblogs.com/wyl1924/p/13937639.html