Net Core 3.x使用Swagger的几个骚操作

有时候，我们的WebAPI可能会涉及到多版本管理，在开发新版本接口的同时又能保障老接口的稳定运行，那么这时候可能会涉及到两个版本的接口，一般我们会在接口上加个版本号，如：v1、v2.

我们来参考下百度地图API的格式

在.net core中，想给接口加上版本号，有多种方式:

1、通过URL Path Segment来实现;
2、通过HTTP Headers来实现;
3、通过QueryString来实现; 具体的实现可以去百度或者Bing。我个人喜欢使用第一种方式。这里，我们继续上个版本再引入一个组件:Microsoft.AspNetCore.Mvc.Versioning Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 现在我先在Controllers文件夹中分别创建v1、v2两个文件夹，用于存放两个版本的API,然后分别在v1和v2下面创建DemoV1Controller、DemoV2Controller两个Controller

DemoV1Controller

//当前Controller的版本号 [ApiVersion(“1.0”)] //接口访问路径 [Route(“api/v{version:apiVersion}/[controller]”)] [ApiController] public class DemoV1Controller : ControllerBase { ///

/// 获取版本号 ///

///

[HttpGet(“version”)] publicstringGetVerison() {return

“v1.0”; } }

DemoV2Controller

//当前Controller的版本号 [ApiVersion(“2.0”)] //接口访问路径 [Route(“api/v{version:apiVersion}/[controller]”)] [ApiController] public class DemoV2Controller : ControllerBase { ///

/// 获取版本号 ///

///

[HttpGet(“version”)] publicstringGetVerison() {return

“v2.0″; } }

接下来我们就去配置Swagger，因为配置代码有点多，所以最好是独立一个配置类,这里我新建一个名为ConfigureSwaggerOptions的配置类

publicclassConfigureSwaggerOptions:IConfigureOptions

{ readonly IApiVersionDescriptionProvider provider;publicConfigureSwaggerOptions(IApiVersionDescriptionProvider provider)=>this.provider = provider;publicvoidConfigure(SwaggerGenOptions options){ foreach (var description in provider.ApiVersionDescriptions) { options.SwaggerDoc(description.GroupName,newOpenApiInfo { Description = $”Demo API {description.ApiVersion} Description”, Version = description.ApiVersion.ToString(), Title = $”Demo API 文档{description.ApiVersion}”, Contact =newOpenApiContact() { Name =”eyiadmin”, Email =”188781475@qq.com”}, License =newOpenApiLicense { Name =”Apache 2.0″, Url =newUri(“http://www.apache.org/licenses/LICENSE-2.0.html”) } }); } var docXmlPath = Path.Combine(AppContext.BaseDirectory, $”{Assembly.GetExecutingAssembly().GetName().Name}.xml”); options.IncludeXmlComments(docXmlPath); } }

好了，现在去Startup.cs类的ConfigureServices注入上面的配置类

publicvoidConfigureServices(IServiceCollection services) { services.AddApiVersioning(); services.AddVersionedApiExplorer(options=>options.GroupNameFormat =”‘v’VVV”); services.AddControllers(); services.AddTransient

, ConfigureSwaggerOptions>(); services.AddSwaggerGen(); }

此时运行起来就可以看到我们的带版本号的新版接口文档，同时，我们可以点击右上角切换不同版本的接口文档

如果我们想要调试接口，点击每个接口里面的Try it out，输入对应的参数即可

多版本接口文档就记这么多了，接下来，我们继续在Swagger中添加Header Authorization

其实Swashbuckle已经给我们提供了很方便的API，只需要配置一下即可:

options.AddSecurityDefinition(“bearer”,newOpenApiSecurityScheme { Type = SecuritySchemeType.Http, In = ParameterLocation.Header, Name =”Authorization”, Scheme =”bearer”, BearerFormat =”JWT”, Description =”JWT Authorization header using the Bearer scheme.”, });varreq =newOpenApiSecurityRequirement(); req.Add(newOpenApiSecurityScheme { Reference =newOpenApiReference { Type = ReferenceType.SecurityScheme, Id =”bearer”} },new[] {“”}); options.AddSecurityRequirement(req);