.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>(); 
             });