.NetCore使用Swagger进行单版本或多版本控制处理

前面已经介绍过了Swagger的基础使用了

下面继续分别详细说明下不添加版本控制以及添加版本控制的使用情况，其实也基本一致，对看起来可能更加容易理解

第一步导入nuget包

nuget导入Swashbuckle.AspNetCore (对应有Swashbuckle.AspNetCore.Swagger、Swashbuckle.AspNetCore.SwaggerGen、Swashbuckle.AspNetCore.SwaggerUI)

版本控制还需要引入

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

Microsoft.AspNetCore.Mvc.Versioning

第二步添加服务及配置

下面代码中都结合了IdentityServer4中的相关设置，可以忽略

非版本控制

ConfigServices中添加如下代码

services.AddSwaggerGen(options =>

            {

                options.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info

                {

                    Version = "v1.0",

                   Title = "体检微服务接口"

                });

                var basePath = PlatformServices.Default.Application.ApplicationBasePath;

                var xmlPath = Path.Combine(basePath, "ExaminationServicesApi.xml");

                options.IncludeXmlComments(xmlPath);

                var xmlmodelPath =

                Path.Combine(basePath, "ExaminationServicesDomain.xml");

                options.IncludeXmlComments(xmlmodelPath);

                #region Swagger添加授权验证服务

                //options.AddSecurityDefinition("Bearer", new ApiKeyScheme

                //{

                //    Description = "JWT Bearer 授权 \"Authorization: Bearer+空格+token\"",

                //    Name = "Authorization",

                //    In = "header",

                //    Type = "apiKey"

                //});

                options.AddSecurityDefinition("oauth2", new OAuth2Scheme

                {

                    Type = "oauth2",

                    Flow = "implicit",

                    AuthorizationUrl = _authorityconfig.Authority + "/connect/authorize",

                    Scopes = new Dictionary<string, string>

                        {

                          //{ "openid", "身份信息" } ,

                          //{ "profile", "个人基本信息" } ,

                          { "userservicesapi", "用户服务" },

                          { "examinationservicesapi", "体检服务" }

                        }

                });

                options.OperationFilter<CustomOperationFilter>();

                #endregion

            });

 app.UseSwagger();

            app.UseSwaggerUI(c =>

            {

                c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApi");

                c.OAuthClientId("testuserservicesapiexaminationservicesapi");

                c.OAuthAppName("体检服务");

            });

这里要注意到我添加了2个xml 一个是apicontroller的获取注释描述，如果需要model相关的描述可以将model所在的应用程序集xml处理下，以便于在接口文档上可以看到model的先关说明

版本控制

ConfigServices中添加如下代码只不过是动态的处理了版本信息

 services.AddApiVersioning(option =>

            {

                option.AssumeDefaultVersionWhenUnspecified = true;

                option.ReportApiVersions = false;

            })

            .AddMvcCore().AddVersionedApiExplorer(option => {

                option.GroupNameFormat = "'v'VVV";

                option.AssumeDefaultVersionWhenUnspecified = true;

            });

            services.AddSwaggerGen(options =>

            {

                var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();

                foreach (var description in provider.ApiVersionDescriptions)

                {

                    options.SwaggerDoc(description.GroupName,

                         new Info()

                        {

                            Title = $"体检微服务接口 v{description.ApiVersion}",

                            Version = description.ApiVersion.ToString(),

                            Description = "切换版本请点右上角版本切换",

                            Contact = new Contact() { Name = "黎又铭", Email = "2939828886@qq.com" }

                        }

                    );

                }

                //options.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info

                //{

                //    Version = "v1.0",

                //    Title = "体检微服务接口"

                //});

                var basePath = PlatformServices.Default.Application.ApplicationBasePath;

                var xmlPath = Path.Combine(basePath, "ExaminationServicesApi.xml");

                options.IncludeXmlComments(xmlPath);

                var xmlmodelPath =

                Path.Combine(basePath, "ExaminationServicesDomain.xml");

                options.IncludeXmlComments(xmlmodelPath);

                #region Swagger添加授权验证服务

                //options.AddSecurityDefinition("Bearer", new ApiKeyScheme

                //{

                //    Description = "JWT Bearer 授权 \"Authorization: Bearer+空格+token\"",

                //    Name = "Authorization",

                //    In = "header",

                //    Type = "apiKey"

                //});

                options.AddSecurityDefinition("oauth2", new OAuth2Scheme

                {

                    Type = "oauth2",

                    Flow = "implicit",

                    AuthorizationUrl = _authorityconfig.Authority + "/connect/authorize",

                    Scopes = new Dictionary<string, string>

                        {

                          //{ "openid", "身份信息" } ,

                          //{ "profile", "个人基本信息" } ,

                          { "userservicesapi", "用户服务" },

                          { "examinationservicesapi", "体检服务" }

                        }

                });

                options.OperationFilter<CustomOperationFilter>();

                #endregion

            });

 app.UseSwagger();

            app.UseSwaggerUI(c =>

            {

                foreach (var description in provider.ApiVersionDescriptions)

                {

                    c.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());

                }

                //c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApi");

                c.OAuthClientId("testuserservicesapiexaminationservicesapi");

                c.OAuthAppName("体检服务");

            });

对比两种情况可以看出实际上就多出来一个办理版本信息而已，ApiVersionDescriptions 其实就是通过这个特性动态遍历了版本信息，所以多版本控制只需要在ApiController中添加好相关的属性标签即可

第三步使用

[ApiVersion("1.0")]

[Route("api/v{api-version:apiVersion}/[controller]")]

 public class DemoController : ControllerBase

{

}

在前面代码中我们用到了 CustomOperationFilter这个处理，在这个操作过滤器中我在之前的代码中添加授权及文件上传，这里我们使用版本控制还需要在里面添加好版本参数描述处理

 public class CustomOperationFilter : IOperationFilter

    {

        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 = description.ModelMetadata.Description;

                }

            }

            #endregion

            #region Swagger授权过期器处理

            if (operation.Security == null)

                operation.Security = new List<IDictionary<string, IEnumerable<string>>>();

            var oAuthRequirements = new Dictionary<string, IEnumerable<string>>

                                        {

                                              {"oauth2", new List<string> { "openid", "profile", "examinationservicesapi" }}

                                        };

            operation.Security.Add(oAuthRequirements);

            #endregion

            #region Swagger 文件上传处理

            var files = context.ApiDescription.ActionDescriptor.Parameters.Where(n => n.ParameterType == typeof(IFormFile)).ToList();

            if (files.Count > )

            {

                for (int i = ; i < files.Count; i++)

                {

                    if (i == )

                    {

                        operation.Parameters.Clear();

                    }

                    operation.Parameters.Add(new NonBodyParameter

                    {

                        Name = files[i].Name,

                        In = "formData",

                        Description = "Upload File",

                        Required = true,

                        Type = "file"

                    });

                }

                operation.Consumes.Add("multipart/form-data");

            }

            #endregion

        }

    }

运行程序看效果

版本控制就搞定了，这里需要说明的是看下面的图

额外说明

版本是不是必须的、以及描述就是在CustomOperationFilter中处理下默认的说明，你可以这样写

 if (parameter.Description == null)

                {

                    parameter.Description ="填写版本号如:1.0";

                }

parameter.Required=false; //设置非必填或非必填

下面看下效果，已经有注释了和设置了的非必填项目

这里额外在说一点的就是

 [ApiVersion("1.0", Deprecated = false)]

Deprecated 这个属性设置 True ：标识是否弃用API ,在设置为true的情况下来看下效果

1.0版本已经是弃用了，这里又要额外说下与这个关联的属性了就是在服务配置选项中的 ReportApiVersions 设置用下面的配置

 services.AddApiVersioning(option =>

            {

                option.ReportApiVersions = false;

            })

            .AddMvcCore().AddVersionedApiExplorer(option => {

                option.GroupNameFormat = "'v'VVV";

                option.AssumeDefaultVersionWhenUnspecified = true;

                option.DefaultApiVersion = new ApiVersion(, );

            });

false:不再请求响应中添加版本报告信息，下图中已经不会显示我一用的版本信息了

上面默认版本 DefaultApiVersion 我设置了1.0 在代码中出现2个版本路由地址一样，在没有填写版本号的情况下使用默认版本

AssumeDefaultVersionWhenUnspecified：true 是否在没有填写版本号的情况下使用默认版本