Swagger 添加版本控制

1、安装

<PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning" Version="5.1.0" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer" Version="5.1.0" />

2、扩展类

/// <summary>
    /// Swagger
    /// </summary>
    public static class SwaggerExtension
    {
        /// <summary>
        /// Swagger注册方法
        /// </summary>
        /// <param name="builder"></param>
        public static void AddSwaggerGenExt(this WebApplicationBuilder builder)
        {
            // API版本控制
            builder.Services.AddApiVersioning(o =>
            {
                o.AssumeDefaultVersionWhenUnspecified = true;
                o.DefaultApiVersion = new ApiVersion(1, 0);
            }).AddVersionedApiExplorer(o =>
            {
                o.GroupNameFormat = "'v'V";
            });
            builder.Services.AddSwaggerGen(c =>
            {
                #region 配置Swagger
                {
                    var provider = builder.Services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();

                    // 多版本控制
                    foreach (var description in provider.ApiVersionDescriptions)
                    {
                        // 添加文档信息
                        c.SwaggerDoc(description.GroupName, new OpenApiInfo
                        {
                            Title = "DaprBackEnd API 接口文档",
                            Version = description.ApiVersion.ToString(),
                            Description = "DaprBackEnd API 接口文档"
                        });
                    }

                    //在Swagger文档显示的API地址中将版本信息参数替换为实际的版本号
                    c.DocInclusionPredicate((Version, ApiDescription) =>
                    {
                        if (!Version.Equals(ApiDescription.GroupName))
                            return false;
                        IEnumerable<string>? values = ApiDescription!.RelativePath
                        .Split('/')
                        .Select(v => v.Replace("V{version}", ApiDescription.GroupName));//"V{version}"： 与Controller中的路由版本配置保持一致
                        ApiDescription.RelativePath = String.Join("/", values);
                        return true;
                    });

                    //取消API文档需要输入版本信息
                    c.OperationFilter<RemoveVersionParameterFilter>();
                    c.DocumentFilter<ReplaceVersionWithExactValueInPathFilter>();
                    // 添加身份认证
                    //c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
                    //{
                    //    Name = "Authorization",
                    //    Type = SecuritySchemeType.ApiKey,
                    //    In = ParameterLocation.Header,
                    //    Description = ""
                    //});
                    //c.AddSecurityRequirement(new OpenApiSecurityRequirement
                    //{
                    //    {
                    //        new OpenApiSecurityScheme
                    //        {
                    //            Reference = new OpenApiReference
                    //            {
                    //                Type = ReferenceType.SecurityScheme,
                    //                Id = "Bearer"
                    //            }
                    //        },
                    //        new string[]{ }
                    //    }
                    //});
                }
                #endregion

                #region 配置展示注释
                {
                    var path = Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml");  // xml文档绝对路径
                    if(File.Exists(path))
                        c.IncludeXmlComments(path, true); // true : 显示控制器层注释
                    c.OrderActionsBy(o => o.RelativePath); // 对action的名称进行排序，如果有多个，就可以看见效果了。
                }
                #endregion
            });
        }

        /// <summary>
        /// Swagger使用方法
        /// </summary>
        /// <param name="app"></param>
        public static void UseSwaggerExt(this WebApplication app)
        {
            #region 使用Swagger
            //使用Swagger
            app.UseSwagger();
            // 配置SwaggerUI
            app.UseSwaggerUI(c =>
            {
                var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
                foreach (var description in provider.ApiVersionDescriptions)
                {
                    c.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", $"DaprBackEnd API {description.GroupName}版本");
                }
            });
            #endregion
        }
    }

3、Program.cs

//调用封装后的注册Swagger
            builder.AddSwaggerGenExt();

            var app = builder.Build();

            // Configure the HTTP request pipeline.
            if (app.Environment.IsDevelopment())
            {
                //封装后的使用Swagger
                app.UseSwaggerExt();
            }

二种添加版本控制的方式：

1.控制器上添加特性：
[Route("V{version:apiVersion}/[controller]/[action]")]
    [ApiController]
    [ApiVersion("1.0")]

2.方式上添加特性：
[MapToApiVersion("1.0")]