一、概述
刚参加工作时，写个API接口，还要写API文档，再使用PostMan测试接口，写文档的时间比写接口还要折腾。后来接触Swagger，API文档的工作得到了很大的改善，不但可以自动构建交互式API说明文档，还能直接调试API接口。今天记录下Core项目下使用Swagger，最新版的Swagger已经完美支持Open Api规范及JWT Token授权访问等。使用Swagger的好处总结如下：
- 使用 Swagger 生成精美的API接口文档
- 使用 Swagger 调试JWT授权接口
- 使用 Swagger 生成各个类库中视图模型的描述
二、使用Swagger
1、新建一个.NET Core 3.1 Web Api 项目，打开Nuget安装管理器，搜索Swashbuckle.AspNetCore，安装即可
2、设置生成XML描述信息
右键--》属性-》生成
3、开始配置Swagger
我们打开Startup.cs文件，来对Swagger配置进行一些必要的配置，在ConfigureServices方法我们添加一下Swagger配置：
public void ConfigureServices(IServiceCollection services) { services.AddControllers(); services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Version = "v1", Title = "TestSwaggerApi", Description = "基于.NET Core 3.1 的测试实例", Contact = new OpenApiContact { Name = "qxh", Email = "2269667628@qq.com" }, }); var baseDirectory = System.AppDomain.CurrentDomain.BaseDirectory; var xmlFile = System.AppDomain.CurrentDomain.FriendlyName + ".xml"; var xmlPath = Path.Combine(baseDirectory, xmlFile); c.IncludeXmlComments(xmlPath); }); }
然后我们在Configure方法里添加swagger中间件：
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseHttpsRedirection(); app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "Test"); c.RoutePrefix = "swagger"; }); app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); }
这样swagger基本配置就完成了，看下效果
三、Swagger启用API文档的JWT授权
目前很多网站都使用了JWT（JSON WEB TOKEN）来作为账户系统的认证授权，JWT以它的简单、高效、分布式优势很快成为了网站的流行验证方式。接下来我们为Swagger添加JWT授权认证，依旧打开Startup.cs文件，修改上面ConfigureServices方法中的代码：
public void ConfigureServices(IServiceCollection services) { services.AddControllers(); services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Version = "v1", Title = "TestSwaggerApi", Description = "基于.NET Core 3.1 的测试实例", Contact = new OpenApiContact { Name = "qxh", Email = "2269667628@qq.com" }, }); c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme() { Description = "在下框中输入请求头中需要添加Jwt授权Token：Bearer Token", Name = "Authorization", In = ParameterLocation.Header, Type = SecuritySchemeType.ApiKey, BearerFormat = "JWT", Scheme = "Bearer" }); c.AddSecurityRequirement(new OpenApiSecurityRequirement { { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" } }, new string[] { } } }); var baseDirectory = System.AppDomain.CurrentDomain.BaseDirectory; var xmlFile = System.AppDomain.CurrentDomain.FriendlyName + ".xml"; var xmlPath = Path.Combine(baseDirectory, xmlFile); c.IncludeXmlComments(xmlPath); }); }
预览一下授权设置，发现右侧多了一个Authorize绿色的带锁按钮，这个按钮点开后就可以设置我们的JWT Token信息了，格式是：Bearer 你的Token字符串，注意Bearer于Token之间有个空格。设置好Token后，你请求任意的API接口时，Swagger会自动附带Token到请求的Header中。
四、创建一个RESTFUL接口
上面我们已经实现了Swagger的各项配置，现在我们新建一个AccountController及一个通用视图模型，让Swagger返回带描述的接口文档。
1、新建AccountController
using Microsoft.AspNetCore.Mvc; namespace SwaggerTest.Controllers { /// <summary> /// 账户接口 /// </summary> [Produces("application/json")] [Route("v1/[controller]")] [ApiController] public class AccountController : ControllerBase { /// <summary> /// 创建信息 /// </summary> /// <param name="commonParamModel">参数</param> /// <returns>状态</returns> [HttpPost] public int Post([FromBody] CommonParamModel commonParamModel) { return 1; } /// <summary> /// 删除信息 /// </summary> /// <param name="commonParamModel">参数</param> /// <returns></returns> [HttpDelete] public int Delete([FromQuery] CommonParamModel commonParamModel) { return 2; } /// <summary> /// 查询信息 /// </summary> /// <param name="commonParamModel">参数</param> /// <returns></returns> [HttpGet] public int Get([FromQuery] CommonParamModel commonParamModel) { return 3; } /// <summary> /// 修改信息 /// </summary> /// <param name="commonParamModel">参数</param> /// <returns></returns> [HttpPut] public int Put([FromQuery] CommonParamModel commonParamModel) { return 4; } } }
2、创建公共视图模型
namespace SwaggerTest { /// <summary> /// 公共参数model /// </summary> public class CommonParamModel { /// <summary> /// ID /// </summary> public long Id { get; set; } /// <summary> /// 账号 /// </summary> public long Account { get; set; } /// <summary> /// 密码 /// </summary> public long Password { get; set; } } }
测试最终成果，随便展开一个API接口，可以看到我们给视图模型写的注释已经显示在Swagger上了，前端开发人员一看就懂，输入一些接口参数，点一下执行就能看到返回值了：
再看我们的请求Header中已经包含了JWT授权信息（Bearer abcdefghi）是我随意设置的，前端调试的时候换成需要的Token就行了。