WebApi + Swagger2.0接口文档多版本控制设计实现
最近前后端分离的项目越来越多，API的对接对于前后端开发交流得最多的一块内容，一个好的API文档生成工具就显得非常重要，选取了Swagger文档生成工具作为项目的文档生成工具，考虑到多版本的文档生成，基于swagger5.6版本实现了一套多版本控制
1. NuGet包引用
比较简单，下面三个包都引用，删掉自动生成的页面文件，本此介绍多版本此处省略NuGet引入的文件清理工作了
2. 多版本控制
找到App_Start文件夹下面的SwaggerConfig，找到下图的节点，默认是c.SingApiVersion生效，先注释此行，再打开c.MultipleApiVersions勾子节点
此处有一个匿名方法调用ResolveVersionSupportByRouteConstraint，此方法需要自己实现，其中apiDesc是当前工程文件实现ApiController的全部路由数据,targetApiVersion是当前版本信息，直接在SwaggerConfig类中生成私有方法，我的实现如下，思路是在此处过滤掉非当前版本的Controller路由
private static bool ResolveVersionSupportByRouteConstraint(ApiDescription apiDesc, string targetApiVersion) { //过滤由多版本的controller带来的重复route注册api desc,按命名空间的版本信息过滤,只返回版本内的api return apiDesc.ActionDescriptor.ControllerDescriptor.ControllerType.FullName.ToLower().Contains(string.Format(".{0}.", targetApiVersion)); }
3. 路由文件版本分离规则
注意工程文件中Controllers的版本是通过命名空间隔离的，上面的代码就是通过版本信息来匹配这个命名空间来实现过滤，假设v1和v2文件夹中都有ValuesController
两个版本的ValuesController如下,route在Map时不能有重复名称的Controller，所以此处采取加上版本，v1不需要添加，v2的ValuesController上加上版本， 借助RoutePrefix为ValuesV2Controller重写路由，对外路由统一为api/{verstion}/Values并不会有ValuesV2出现在api路由上，此处的ValuesV2在文档生成时还需要特殊处理，下面会重点提到IDocumentFilter接口实现时的处理
4. 多版本路由注册
此时在WebApiConfig的路由注册中写下如下代码，分别注册两个版本的路由对应v1,v2版本
config.Routes.MapHttpRoute( name: "DefaultApi", routeTemplate: "api/v1/{controller}/{id}", defaults: new { id = RouteParameter.Optional} ); config.Routes.MapHttpRoute( name: "Apiv2", routeTemplate: "api/v2/{controller}/{id}", defaults: new { id = RouteParameter.Optional } );
5. IDocumentFilter接口实现
多版本的控制到这就算基本实现了，只不过ValuesV2这个路由的文档中依然会带上这个V2, 由于我们在RoutePrefix中已经配置了V2的Values路由是api/v2/Values，但按路由注册规则文档生成的路由默认会是api/v2/ValuesV2, 如果按文档生成的路径调用时会报找不到文件，原因就是RoutePrefix生效的路由与Swagger文档路由不匹配，好在Swagger提供的过滤接口能帮助我们自定义过滤规则，在SwaggerConfig中找到如下节点，打开注释，其中ApplyDocumentVendorExtensions需要我们自己实现
c.DocumentFilter<ApplyDocumentVendorExtensions>();
实现IDocumentFilter接口的ApplyDocumentVendorExtensions文档处理类
internal class ApplyDocumentVendorExtensions : IDocumentFilter { /// <summary> /// //swagger版本控制过滤 /// </summary> /// <param name="swaggerDoc">文档</param> /// <param name="schemaRegistry">schema注册</param> /// <param name="apiExplorer">api概览</param> public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer) { //缓存目标路由api IDictionary<string, PathItem> match = new Dictionary<string, PathItem>(); //取版本 var version = swaggerDoc.info.version; foreach (var path in swaggerDoc.paths) { //过滤命名空间 按名称空间区分版本 if (path.Key.Contains(string.Format("/{0}/", version))) { //匹配controller descript中的版本信息 Regex r = new Regex("/\w+" + version, RegexOptions.IgnoreCase); string newKey = path.Key; if (r.IsMatch(path.Key)) { var routeinfo = r.Match(path.Key).Value; //修正controller别名路由符合RoutePrefix配置的路由 如api/v2/ValuesV2 修正为 api/v2/Values newKey = path.Key.Replace(routeinfo, routeinfo.Replace(version.ToLower(), "")).Replace( routeinfo, routeinfo.Replace(version.ToUpper(), "")); } //保存修正的path match.Add(newKey, path.Value); } } //当前版本的swagger document swaggerDoc.paths = match; } }
至此多版本控制就实现了，其中要注意的地方是Controllers下的V1,V2文件夹下的Controller文件的命名空间要保持默认命名空间，效果如下
ValuesV2请求的实际路由已修正
有部分朋友询问SwaggerConfig中的勾子方法使用，本文重点在搭建SwaggerConfig在线文档和多版本实现，勾子方法推荐使用的几个方法下面简单介绍下：
开启数据模型注释在文档中生成，参数为当前应用程序依赖的数据模型程序集名称，GetXmlPath自己实现
c.IncludeXmlComments(GetXmlPath("DataModel"));
//控制器描述Provider，Swagger提供了ISwaggerProvider接口，供自定义实现控制器的描述在文档中的生成，CachingSwaggerProvider需要自己实现ISwaggerProvider接口
c.CustomProvider((defaultProvider) => new CachingSwaggerProvider(defaultProvider));
//Action相关描述
c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
Swagger接口文档页面中的label汉化js文件，来源网络
c.InjectJavaScript(thisAssembly, "WebApi.Scripts.Swagger-Custom.js");
有可运行的demo没找到地方上传，欢迎索取
--晴天的故事