.Net WebApi 实现接口版本控制并打通Swagger支持( 二 ) _.Net

SwaggerOperationFilter.cs
/// <summary>/// swagger 集成多版本api自定义设置/// </summary>public class SwaggerOperationFilter : IOperationFilter{public void Apply(OpenApiOperation operation, OperationFilterContext context){var apiDescription = context.ApiDescription;//判断接口遗弃状态，对接口进行标记调整operation.Deprecated |= apiDescription.IsDeprecated();if (operation.Parameters == null){return;}//为 api-version 参数添加必填验证foreach (var parameter in operation.Parameters){var description = apiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);if (parameter.Description == null){parameter.Description = description.ModelMetadata?.Description;}if (parameter.Schema.Default == null && description.DefaultValue != null){parameter.Schema.Default = new OpenApiString(description.DefaultValue.ToString());}parameter.Required |= description.IsRequired;}}}这些都配置完成之后，开始对控制模块进行调整
为了方便代码的版本区分，所以我这里在 Controllers 下按照版本建立的独立的文件夹 v1 和 v2
然后在 v1 和 v2 的文件夹下防止了对于的 Controllers ，如下图的结构

文章插图

然后只要在对应文件夹下的控制器头部加入版本标记
[ApiVersion("1")] [ApiVersion("2")] [ApiVersion("......")]
如下图的两个控制器

文章插图

这样就配置好了两个版本的 UserController 具体控制器内部的代码可以不同，然后运行项目观察 Swagger UI 就会发现如下图：

文章插图

? 可以通过 SwaggerUI 右上角去切换各个版本的 SwaggerDoc

文章插图

?点击单个接口的 Try it out 时接口这边也同样会出现一个 api-version 的字段，因为我们这边是配置的从 Header 传入该参数所以从界面中可以看出该字段是从 Header 传递的，如果想要从 url 传递，主要调整上面注册 api 版本控制服务那边的设置为从 Query 传入即可。
至此基础的 api 版本控制逻辑就算完成了。
下面衍生讲解一下如果项目中有部分 api 控制器并不需要版本控制，是全局通用的如何处理，有时候我们一个项目中总会存在一些基础的 api 是基本不会变的，如果每次 api 版本升级都把所有的控制器都全部升级显然太过繁琐了，所以我们可以把一些全局通用的控制器单独标记出来。
只要在这些控制器头部添加 [ApiVersionNeutral] 标记即可，添加了 [ApiVersionNeutral] 标记的控制器则表明该控制器退出了版本控制逻辑，无论 app 前端传入的版本号的是多少，都可以正常进入该控制的逻辑。如下
[ApiVersionNeutral][ApiController][Route("api/[controller]")]public class FileController : ControllerBase{}还有一种就是当我们的 api 版本升级之后，我们希望标记某个 api 已经是弃用的，则可以使用 Deprecated 来表示该版本的 api 已经淘汰。

[ApiVersion("1", Deprecated = true)][ApiController][Route("api/[controller]")]public class UserController : ControllerBase{[HttpPost("CreateUser")]public void CreateUser(DtoCreateUser createUser){//内部注册逻辑此处省略}}

添加淘汰标记之后运行 SwaggerUI 就会出现下图的样式