.net core 3.x Web API使用Swagger添加多版本以及JWT Authorization

很多时候，要给我们的接口升级，但是又怕影响之前的接口业务或者是要开发特定的接口，我们会给接口加上一个版本号，保障老接口依然能稳定运行，例如百度的坐标转换服务

http://api.map.baidu.com/geoconv/v1/?coords=114.21892734521,29.575429778924&from=1&to=5&ak=你的密钥 //GET请求

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

• 1、通过URL Path Segment来实现;
• 2、通过HTTP Headers来实现;
• 3、通过QueryString来实现;
  具体的实现可以去百度或者bing。这里暂时只讲swagger doc实现多版本切换。我个人喜欢使用第一种方式。

ApiExplorer组件的使用

在实现多版本Web API，我们需要借助一个组件:

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

成功添加依赖包后，就可以在程序中使用相应的API了，首先我们先创建如下的目录结构(大家可随意):

接下来，就将我们之前的Controller类上添加相应的特性:

//当前Controller的版本号
[ApiVersion("1.0")]
//接口访问路径
[Route("api/v{version:apiVersion}/[controller]")]

然后在Startup的ConfigureServices中使用ApiExplorer

services.AddApiVersioning();
services.AddVersionedApiExplorer(options => options.GroupNameFormat = "'v'VVV");

Swagger中多版本API文档

下面，我就用Swagger来自动生成多版本文档，为了使我的Startup类相对简洁，我们新建一个ConfigureSwaggerOptions类来放置Swagger的相关配置,完整代码如下：

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
   {
       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, "Web.xml");
           options.IncludeXmlComments(docXmlPath);
       }
   }

修改Startup类
ConfigureServices中:

services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
services.AddSwaggerGen();

Configure中

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IApiVersionDescriptionProvider provider)
       {

           if (env.IsDevelopment())
           {
               app.UseSwagger();
               app.UseSwaggerUI(options =>
               {
                   foreach (var description in provider.ApiVersionDescriptions)
                   {
                       options.SwaggerEndpoint(
                           $"/swagger/{description.GroupName}/swagger.json",
                           description.GroupName.ToUpperInvariant());
                   }
               });
               app.UseDeveloperExceptionPage();
           }

           app.UseHttpsRedirection();

           app.UseRouting();

           app.UseAuthorization();
         
           app.UseEndpoints(endpoints =>
           {
               endpoints.MapControllers();
           });
       }

最终效果如下：


可以点击Select a definition切换我们不同版本的doc

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

效果如下:

我们会看到有一个Authorization的按钮，我们点击可以输入我们获取到的Jwt Token,在文本框内不需要输入Bearer关键字，Swagger会自动为我们加上Bearer关键字。在这里也需要注意到Swagger的坑，因为大写的问题可能会导致Authorization无法添加到request请求头中.下面是Swagger的build-request.js

else if (type === 'http') {
         if (schema.scheme === 'basic') {
         let scheme = schema.scheme;
         if (scheme) {
           scheme = scheme.toLowerCase()
         }

         if (scheme === 'basic') {
           const {username, password} = value
           const encoded = btoa(`${username}:${password}`)
           result.headers.Authorization = `Basic ${encoded}`
         }

         if (schema.scheme === 'bearer') {
         if (scheme === 'bearer') {
           result.headers.Authorization = `Bearer ${value}`
         }
       }

大家可以自己去看看代码，我继续说Authorization的设置，点击按钮就会出现设置token的文本框:

设置完后，我们的小锁会变为关闭状态:

最后就可以通过Swagger UI调用我们的接口，就可以在我们的请求中看到Authorization的参数内容，后端就可以接受处理.

当然，Swagger还有其他的自定义UI功能，大家可以去官网查询相关文档。