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);

可以看到接口列表右上角多了一个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


扫一扫,分享到微信

猜你喜欢

上一篇

阿里开源首个 Serverless 开发者平台

下一篇

Hadoop实现高可用(HA)之自动容灾配置