技术编程|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")]public string GetVerison() {return "v1.0";}}
DemoV2Controller//当前Controller的版本号[ApiVersion("2.0")]//接口访问路径[Route("api/v{version:apiVersion}/[controller]")][ApiController]public class DemoV2Controller : ControllerBase{///
/// 获取版本号///
///
[HttpGet("version")]public string GetVerison(){return "v2.0";}}
接下来我们就去配置Swagger ， 因为配置代码有点多 ， 所以最好是独立一个配置类,这里我新建一个名为ConfigureSwaggerOptions的配置类public class ConfigureSwaggerOptions : IConfigureOptions
{readonly IApiVersionDescriptionProvider provider;public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) =>this.provider = provider;public void Configure(SwaggerGenOptions options){foreach (var description in provider.ApiVersionDescriptions){options.SwaggerDoc(description.GroupName, new OpenApiInfo{Description = $"Demo API {description.ApiVersion} Description",Version = description.ApiVersion.ToString(),Title = $"Demo API 文档{description.ApiVersion}",Contact = new OpenApiContact() { Name = "eyiadmin", Email = "188781475@qq.com" },License = new OpenApiLicense{Name = "Apache 2.0",Url = new Uri("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注入上面的配置类public void ConfigureServices(IServiceCollection services){services.AddApiVersioning();services.AddVersionedApiExplorer(options => options.GroupNameFormat = "'v'VVV");services.AddControllers();services.AddTransient
, ConfigureSwaggerOptions>();services.AddSwaggerGen();}
此时运行起来就可以看到我们的带版本号的新版接口文档 ， 同时 ， 我们可以点击右上角切换不同版本的接口文档
本文插图
本文插图
如果我们想要调试接口 ， 点击每个接口里面的Try it out ， 输入对应的参数即可
本文插图
多版本接口文档就记这么多了 ， 接下来 ， 我们继续在Swagger中添加Header Authorization一般情况下 ， 我们的Web API是使用Jwt来保障接口安全 ， 当然还有很多其他的方式 ， 我只是选择一种相对简单一些的方式 。 这里只是说怎么在Swagger调试的时候带上我们的Jwt Token ， 具体的Jwt实现 ， 也请自己实现 。
其实Swashbuckle已经给我们提供了很方便的API ， 只需要配置一下即可:options.AddSecurityDefinition("bearer", new OpenApiSecurityScheme{Type = SecuritySchemeType.Http,In = ParameterLocation.Header,Name = "Authorization",Scheme = "bearer",BearerFormat = "JWT",Description = "JWT Authorization header using the Bearer scheme.",});var req = new OpenApiSecurityRequirement();req.Add(new OpenApiSecurityScheme{Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "bearer" }}, new[] { "" });options.AddSecurityRequirement(req);
本文插图
可以看到接口列表右上角多了一个Authorize的图标 ， 我们点击可以输入我们获取到的Jwt Token,在文本框内不需要输入Bearer关键字 ， Swagger会自动为我们加上Bearer关键字 。
本文插图
本文插图
此时再来调用接口时 ， 就会自动在我们的请求上加上authorization这个请求头
本文插图
当然 ， 也可以通过Swashbuckle.AspNetCore.Filters来添加请求头 ， 另外 ， 我们在开发WebApi的时候 ， 也会有涉及到上传文件的场景 ， Swashbuckle也为我们提供好了API ， 我们新增一个文件上传接口///
/// 上传文件///
///
///
[HttpPost("upload")]public string UploadFile(IFormFile file){return "";}
然后在ConfigureSwaggerOptions新增一条配置options.MapType(typeof(IFormFile), () => new OpenApiSchema() { Type = "file", Format = "binary" });
这样一来 ， Swashbuckle会为我们生产相应的组件来供我们测试
本文插图
【技术编程|Net Core 3.x使用Swagger时的几个骚操作】
推荐阅读
- 小龙虾|三农探析：池塘养殖小龙虾如何高产？高产养殖技术全解析
- 大棚蔬菜|早春大棚蔬菜病虫害防治技术要点，老农讲得太实用了
- 松树|松烂皮病的发生规律和防治技术-松树枯梢病防治技术
- 中煤科工集团|中煤科工集团西安研究院研发煤层气（瓦斯）地面抽采新技术
- 航空航天|医学和航空航天跨专业碰撞，胡盛寿院士团队打破pVAD技术海外垄断
- 四川|解码四川科技丨打破国外垄断！这项技术每年救治上万名甲状腺癌患者
- 番茄|每平方米产量达到70公斤？五大技术特点解密荷兰的温室番茄高产原因！
- 芒果|村宝网-芒果抽穗期和开花期怎么管理，芒果开花期技术要点，要注意什么
- 智慧农业|物联网技术如何风驰智慧农业？
- 面部识别技术|无处不在的面部识别技术，究竟“恐怖”在哪里？