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

 

posted @ 2018-12-06 10:33  皓月青峰  阅读(2416)  评论(1编辑  收藏  举报