NetCore Swagger 多版本

1.版本枚举

1.     /// <summary>
2.     /// swagger 多版本枚举
3.     /// </summary>
4.     public enum SwaggerVersionEnum
5.     {
6.         /// <summary>
7.         /// V1 版本，复杂情况可通过特性获取
8.         /// </summary>
9.         [Description("V1.000")]
10.         V1 = 1000,
11.         /// <summary>
12.         /// V2 版本，复杂情况可通过特性获取
13.         /// </summary>
14.         [Description("V2.000")]
15.         V2 = 2000,
16.         /// <summary>
17.         /// V2 版本，复杂情况可通过特性获取
18.         /// </summary>
19.         [Description("V3.000")]
20.         V3 = 3000,
21.     }

复制代码

2.自定义特性，重写路由

1. using Microsoft.AspNetCore.Mvc;
2. using Microsoft.AspNetCore.Mvc.ApiExplorer;
3. using System;
5.     /// <summary>
6.     /// 自定义路由 /api/{version}/[controler]/[action]
7.     /// </summary>
8.     [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
9.     public class SwaggerVersionAttribute : RouteAttribute, IApiDescriptionGroupNameProvider
10.     {
11.         /// <summary>
12.         /// 分组名称,是来实现接口 IApiDescriptionGroupNameProvider
13.         /// </summary>
14.         public string GroupName { get; set; }
16.         /// <summary>
17.         /// 自定义路由构造函数，继承基类路由
18.         /// </summary>
19.         /// <param name="actionName"></param>
20.         public SwaggerVersionAttribute(string actionName = "[action]") : base("/api/{version}/[controller]/" + actionName)
21.         {
22.         }
23.         /// <summary>
24.         /// 自定义版本+路由构造函数，继承基类路由
25.         /// </summary>
26.         /// <param name="actionName"></param>
27.         /// <param name="version"></param>
28.         public SwaggerVersionAttribute(SwaggerVersionEnum version, string actionName = "[action]") : base($"/api/{version.GetDescription()}/[controller]/{actionName}")
29.         {
30.             GroupName = version.GetDescription();
31.         }
32.     }

复制代码

3.接口使用特性

1.         /// <summary>
2.         /// add2
3.         /// </summary>
4.         /// <param name="dto"></param>
5.         /// <returns></returns>
6.         [HttpPost, SwaggerVersion(SwaggerVersionEnum.V2, "add")]
7.         public async Task<int> V2_Add([FromBody] ProductDto dto)
8.         {
9.             await Task.Run(() => { });
10.             return 1;
11.         }

复制代码

5.修改swagger配置

1.         /// <summary>
2.         /// 添加服务: swagger
3.         /// </summary>
4.         /// <param name="services"></param>
5.         /// <returns></returns>
6.         public static void AddCustSwagger(this IServiceCollection services)
7.         {
8.             var version = "V1.0";
9.             var apiName = "XXX系统";
10.             //  swagger多版本配置
11.             var basePath = Directory.GetCurrentDirectory();
12.             services.AddSwaggerGen(c =>
13.             {
14.                 //var versionList = typeof(SwaggerVersionEnum).GetEnumNames();
15.                 var versionList = EnumExtend.GetEnumList<SwaggerVersionEnum>().Select(x => x.Description);
16.                 versionList.ToList().ForEach(version =>
17.                 {
18.                     c.SwaggerDoc(version, new OpenApiInfo//"V1"
19.                     {
20.                         Version = version,
21.                         Title = $"{apiName} 接口文档",
22.                         Description = $"{apiName} HTTP API {version}",
23.                         //Contact = new OpenApiContact { Name = apiName, Email = "swagger@xxx.com", Url = new Uri("https://www.cnblogs.com/CRobot/") },
24.                         //License = new OpenApiLicense { Name = apiName, Url = new Uri("https://www.cnblogs.com/CRobot/") }
25.                     });
26.                     c.OrderActionsBy(o => o.RelativePath);
28.                     //  获取应用程序xml所在目录
29.                     var xmlPath = Path.Combine(basePath, "ProjectName.xml");
30.                     //  swagger界面默认只显示 方法&字段 注释，不显示 控制器注释
31.                     //  第二个参数为true， 则是controller的注释
32.                     c.IncludeXmlComments(xmlPath, true);
33.                 });
34.             });
35.         }
37.         /// <summary>
38.         /// 添加中间件: swagger
39.         /// </summary>
40.         /// <param name="app"></param>
41.         public static void UseCustSwagger(this IApplicationBuilder app)
42.         {
43.             app.UseSwagger();
44.             app.UseSwaggerUI(options =>
45.             {
46.                 //  swagger多版本配置
47.                 var apiName = "XXX系统";
48.                 //根据版本名称倒序 遍历展示
49.                 //var versionList = typeof(SwaggerVersionEnum).GetEnumNames();
50.                 var versionList = EnumExtend.GetEnumList<SwaggerVersionEnum>().Select(x => x.Description);
51.                 versionList.OrderByDescending(e => e).ToList().ForEach(version =>
52.                 {
53.                     options.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{apiName} {version}");
54.                 });
55.                 //  默认路径为：/swagger/index.html
56.                 //  路由前缀 - 设置为空，可直接跳转到swagger页面：/index.html
57.                 //  api测试可设置为空，部署时容易与前端路由冲突
58.                 options.RoutePrefix = string.Empty;
59.             });
60.         }

复制代码

 
Reference:

NetCore 配置Swagger
   

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！