.NetCore使用Swagger+API多版本控制的流程分析

 services.AddSwaggerGen(c => { c.SwaggerDoc("V1", new OpenApiInfo { //版本 Version = "V1", //标题 Title = $"接口文档-NetCore3.1", //描述 Description = $"NetCore Http API v1", //联系方式 Contact = new OpenApiContact { Name = "测试", Email = "", Url = new Uri("https://www.cnblogs.com/mzflog/") }, License = new OpenApiLicense { Name = "测试2", Url = new Uri("https://www.cnblogs.com/mzflog/") } }); // 加载XML注释 c.IncludeXmlComments(XmlCommentsFilePath); });

 /// 
 /// 获取当前项目名的XML文件 /// 
 static string XmlCommentsFilePath { get { var basePath = PlatformServices.Default.Application.ApplicationBasePath; var fileName = typeof(Startup).GetTypeInfo().Assembly.GetName().Name + ".xml"; return Path.Combine(basePath, fileName); } }

 app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"NetCore V1"); //c.RoutePrefix = string.Empty;     //如果是为空 访问路径就为 根域名/index.html,注意localhost:8001/swagger是访问不到的 //路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件 c.RoutePrefix = "swagger"; // 如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "swagger"; 则访问路径为 根域名/swagger/index.html });

 services.AddApiVersioning(option => { // 可选，为true时API返回支持的版本信息 option.ReportApiVersions = true; // 请求中未指定版本时默认为1.0 option.DefaultApiVersion = new ApiVersion(1, 0); //版本号以什么形式，什么字段传递 option.ApiVersionReader = ApiVersionReader.Combine(new HeaderApiVersionReader("api-version")); // 在不提供版本号时，默认为1.0  如果不添加此配置，不提供版本号时会报错"message": "An API version is required, but was not specified." //option.AssumeDefaultVersionWhenUnspecified = true; //默认以当前最高版本进行访问 //option.ApiVersionSelector = new CurrentImplementationApiVersionSelector(option); }).AddVersionedApiExplorer(opt => { //以通知swagger替换控制器路由中的版本并配置api版本 opt.SubstituteApiVersionInUrl = true; // 版本名的格式：v+版本号 opt.GroupNameFormat = "'v'VVV"; //是否提供API版本服务 opt.AssumeDefaultVersionWhenUnspecified = true; });

 //方式一 （不建议使用）   此种方式报警告：ASP0000 从应用程序代码调用“BuildServiceProvider”会导致创建单例服务的附加副本。考虑替代方案，例如将依赖注入服务作为“配置”的参数 services.AddSwaggerGen(options => { // 解析IApiVersionDescriptionProvider服务 var provider = services.BuildServiceProvider().GetRequiredService(); //为每个发现的API版本添加一个swagger文档 可跳过不需要记录的 foreach (var description in provider.ApiVersionDescriptions) { options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description)); } 　　　　 //加载XML注释  并启用控制器的注释信息默认为false不启用 options.IncludeXmlComments(XmlCommentsFilePath,true); }); //方式二 （建议使用） services.AddSwaggerGen(); //解决上面报ASP0000警告的方案 services.AddOptions() .Configure((options, service) => { options.ResolveConflictingActions(apiDescriptions => apiDescriptions.First()); // 添加文档信息 foreach (var item in service.ApiVersionDescriptions) { options.SwaggerDoc(item.GroupName, CreateInfoForApiVersion(item)); } //给swagger添加过滤器 //options.OperationFilter(); // 加载XML注释 options.IncludeXmlComments(XmlCommentsFilePath, true); });

 static OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description) { var info = new OpenApiInfo() { //标题 Title = $".NET Core API for 测试项目 {description.ApiVersion}", //当前版本 Version = description.ApiVersion.ToString(), //文档说明 Description = "api项目 当前环境-" + EnvironmentName, //联系方式 Contact = new OpenApiContact() { Name = "标题", Email = "", Url = null }, TermsOfService = new Uri(""), //许可证 License = new OpenApiLicense() { Name = "文档", Url = new Uri("") } };　　　　　 //当有弃用标记时的提示信息 if (description.IsDeprecated) { info.Description += " - 此版本已放弃兼容"; } return info; }

 //添加Swagger中间件，主要用于拦截swagger.json请求，从而可以获取返回所需的接口架构信息 app.UseSwagger(opt => { //路由模板，默认值是/swagger/{documentName}/swagger.json，这个属性很重要！而且这个属性中必须包含{documentName}参数。 //opt.RouteTemplate= "/swagger/{documentName}/swagger.json"; // 表示按Swagger2.0格式序列化生成swagger.json，这个不推荐使用，尽可能的使用新版本的就可以了 //opt.SerializeAsV2 }); //添加SwaggerUI中间件，主要用于拦截swagger / index.html页面请求，返回页面给前端 app.UseSwaggerUI(options => { // 为每个版本创建一个JSON foreach (var description in provider.ApiVersionDescriptions) { //这个属性是往SwaggerUI页面head标签中添加我们自己的代码，比如引入一些样式文件，或者执行自己的一些脚本代码 //options.HeadContent += $""; //展示默认头部显示的下拉版本信息 //options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant()); //自由指定头部显示的下拉版本内容 options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", "coreApi" + description.ApiVersion); //如果是为空 访问路径就为 根域名/index.html,注意localhost:8001/swagger是访问不到的 //options.RoutePrefix = string.Empty; // 如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "swagger"; 则访问路径为 根域名/swagger/index.html options.RoutePrefix = "swagger"; } });

 [ApiVersion("1.0", Deprecated = false)] //Deprecated是否弃用该版本 默认为false不弃用。即使标记了弃用此接口还是会显示，只是做个提示此版本将会被弃用了。 [Route("api/[controller]")] [ApiController] //[ApiExplorerSettings(IgnoreApi = true)] 隐藏该接口Controller public class ValuesController : Controller [Obsolete] //弃用该Action方法 [ApiExplorerSettings(IgnoreApi = true)] //隐藏该Action方法 public IEnumerable Get()