.net core webapi 定义多版本与 Swagger 的文档输出

前提：

　　需要nuget  以下两个程序集

　　　　　　　　Swashbuckle.AspNetCore 我暂时用的是  4.01；

　　　　　　　　Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer    2.2.0

描述：解决 .net core  webapi 同一个项目中，多个版本的控制及文档输出；

 Controllers 层次如下：

 

实际效果：(引用他人的git图片)

　　

 

解决办法：

　　步骤1  对startup.cs 进行修改代码如下：

　　　　1.1 增加私有变量：  

/// <summary>
/// Api版本提者信息
/// </summary>
private IApiVersionDescriptionProvider provider;

　　　　1.2 在配置服务 ConfigureServices 中增加如下代码：

            services.AddApiVersioning(option =>
            {
                option.AssumeDefaultVersionWhenUnspecified = true;
                option.ReportApiVersions = false;
            })
            .AddMvcCore().AddVersionedApiExplorer(option =>
            {
                option.GroupNameFormat = "'v'VVV";
                option.AssumeDefaultVersionWhenUnspecified = true;
            });

            this.provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
            services.AddSwaggerGen(options =>
            {
                foreach (var description in provider.ApiVersionDescriptions)
                {
                    options.SwaggerDoc(description.GroupName,
                         new Info()
                         {
                             Title = $"接口 v{description.ApiVersion}",
                             Version = description.ApiVersion.ToString(),
                             Description = "切换版本请点右上角版本切换"
                         }
                    );
                }
              options.IncludeXmlComments(this.GetType().Assembly.Location.Replace(".dll", ".xml"), true);
            });

　　　　1.3 在配置http管道 Configure 中增加如下代码：

            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                foreach (var description in provider.ApiVersionDescriptions)
                {
                    c.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
                }
            });

 

 　　步骤2 对Controllers 配置相应版本信息

　　不同的版本只需改变    [ApiVersion("x.x.x")]

    /// <summary>
    /// 1.0 版本
    /// </summary>
    [ApiController]
    [ApiVersion("1.0")]
    [Route("api/v{version}/[controller]/[action]")]
    public class EasenController : ControllerBase
    {
         ..................
    }

 

　　步骤3 为了更好的在Swagger 文档调试的时候自动填入相应的版本号进行优化

　　　　3.1 增加 SwaggerOperationFilter.cs 代码如下：

    /// <summary>
    /// Swagger 过滤器
    /// </summary>
    public class SwaggerOperationFilter : IOperationFilter
    {
        /// <summary>
        /// 应用过滤器
        /// </summary>
        /// <param name="operation"></param>
        /// <param name="context"></param>
        public void Apply(Operation operation, OperationFilterContext context)
        {
            #region Swagger版本描述处理
            foreach (var parameter in operation.Parameters.OfType<NonBodyParameter>())
            {
                var description = context.ApiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);
                if (parameter.Description == null)
                {
                    parameter.Description = "填写版本号如:1.0";
                    parameter.Default = context.ApiDescription.GroupName.Replace("v", "");
                }
            }
            #endregion
      }
}

　　　　　　3.2 在 startup.cs   ConfigureServices  中对 AddSwaggerGen 配置项进行修改代码如下：

　　　　　　　　services.AddSwaggerGen(options =>
　　　　　　　　{
                ...............
                options.OperationFilter<SwaggerOperationFilter>(); 
             });