有时候，我们的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 ="[email protected]"}, 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);
可以看到接口列表右上角多了一个Authorize的图标，我们点击可以输入我们获取到的Jwt Token,在文本框内不需要输入Bearer关键字，Swagger会自动为我们加上Bearer关键字。
此时再来调用接口时，就会自动在我们的请求上加上authorization这个请求头
当然，也可以通过Swashbuckle.AspNetCore.Filters来添加请求头，另外，我们在开发WebApi的时候，也会有涉及到上传文件的场景，Swashbuckle也为我们提供好了API，我们新增一个文件上传接口
///
/// 上传文件////summary>///
"file">/param>///
/returns>[HttpPost("upload")]public string UploadFile(IFormFile file){return "";}
然后在ConfigureSwaggerOptions新增一条配置
options.MapType(typeof(IFormFile),()=>newOpenApiSchema() { Type ="file", Format ="binary"});
这样一来，Swashbuckle会为我们生产相应的组件来供我们测试
原文地址：https://t.cj.sina.com.cn/articles/view/1840767933/6db7e3bd00101zsya?from=tech&subch=otech
转载请注明出处：http://www.donr.com.cn/853.html
本文由 华域联盟 原创撰写：华域联盟 » Net Core 3.x使用Swagger的几个骚操作
转载请保留出处和原文链接：https://www.cnhackhy.com/13114.htm
