你知道如何在.Net中使用Swagger基础知识吗？转载本文请联系鹏翔公众号。简介Swagger是用于生成、描述、调用和可视化RESTfulWeb服务的规范和完整框架。可日常用于后端开发人员测试接口或前后端联调。从.net5开始，swagger已经集成到vs2019编译器中，勾选“EnableOpenAPIsupport”选项即可显示基本的swagger配置。本文示例环境：vs2019，net51基本用于新建NetCoreAPI工程。为了测试效果，我又创建了几个controllerimage.png1.1来安装组件1.2注册swagger服务在ConfigureServicespublicvoidConfigureServices(IServiceCollectionservices){services.AddControllers();services.AddSwaggerGen(c=>{c.SwaggerDoc("v1",newOpenApiInfo{Title="WebApi",Version="v1"});});}注意：//netcore3.0版本使用前c.SwaggerDoc("v1",newInfo{Title="WebApi",Version="v1"});1.3使用SwaggerpublicvoidConfigure(IApplicationBuilderapp,IWebHostEnvironmentenv){if(env.IsDevelopment()){app.UseDeveloperExceptionPage();app.UseSwagger();app.UseSwaggerUI(c=>c.SwaggerEndpoint("/swagger/v1/swagger.json","WebApiv1"));}app.UseRouting();app.UseAuthorization();app.UseEndpoints(endpoints=>{endpoints.MapControllers();});}本示例代码配置的swagger只显示在开发环境，可根据实际显示修改1.4，根据情况启动运行项目，出现如下效果image.png如果这是你写的界面，你其他同事这时候再看，真的会一头雾水。你在写什么，那我们来注释这个//////用户控制器///[Route("api/[controller]")][ApiController]publicclassUserController:ControllerBase{//////查询用户列表//////[HttpGet]publicIEnumerableGet(){returnnewstring[]{"value1","value2"};}//////查询用户详情/////////[HttpGet("{id}")]publicstringGet(intid){return"value";}//////删除用户//////[HttpDelete("{id}")]publicvoidDelete(intid){}}这样添加注释还不够，swagger还是看不懂我们的注释，我们还需要生成xml文档让swagger使用，选择项目右键属性=>生成=>xml文档文件image.png修改Injectswaggerconfigurationservices.AddSwaggerGen(c=>{c.SwaggerDoc("v1",newOpenApiInfo{Title="WebApi",Version="v1"});//使用反射获取xml文件。并构造文件的路径varxmlFile=$"{Assembly.GetExecutingAssembly().GetName().Name}.xml";varxmlPath=Path.Combine(AppContext.BaseDirectory,xmlFile);//启用xml注释。第二个参数开启控制器的注释，默认为false.c.IncludeXmlComments(xmlPath,true);});再次启动项目查看界面image.png至此基本配置swagger显示注释已经实现，那么如何调用我们的界面呢？image.png通过该接口，我们可以看到请求地址，请求方法，入参类型，输出参数等。注：通过设置取消显示警告：1591，可以去掉方法和类上面的xml注释警告.如果实体类不在当前程序集下，则需要用同样的方法将实体类程序集的xml文档配置到swagger配置中。2.swaggerpassesJWTjwt是一种基于JSON的token，用于在网络上声明某些声明，通常由三部分组成：header信息，messagebody，signature。它是用于在两方之间传递安全信息的声明性声明规范。一个可以做权限验证的工具，但目的不是为了数据加密和保护。虽然看起来是加密数据，但实际上并没有加密，不适合存放机密信息。如果我们的接口需要通过token来访问，那么就需要修改我们的swagger配置services.AddSwaggerGen(c=>{c.SwaggerDoc("v1",newOpenApiInfo{Title="WebApi",Version="v1"});//使用反射获取xml文件。并构造文件的路径varxmlFile=$"{Assembly.GetExecutingAssembly().GetName().Name}.xml";varxmlPath=Path.Combine(AppContext.BaseDirectory,xmlFile);//启用xml注释。第二个参数Enablecontrollercomments，默认为false"Bearer",newOpenApiSecurityScheme(){Description="JWT授权（数据会在请求头中传输）下面输入Bearer{token}即可，注意两者之间有一个空格",Name="Authorization",//jwtdefaultIn=ParameterLocation.Header的参数名,//jwt默认存放授权信息的位置(在请求头中)Type=SecuritySchemeType.ApiKey,});c.AddSecurityRequirement(newOpenApiSecurityRequirement{{newOpenApiSecurityScheme{Reference=newOpenApiReference(){Id="Bearer",Type=ReferenceType.SecurityScheme}},Array.Empty()}});});运行，查看界面，发现界面不一样image.png虽然我没有token，但是我也没有写验证token的代码，所以我们暂时用它来作为header传输工具.jwt的具体使用后面会讲到。token传递方式是在Headers中添加Authorization:Bearer{token}，然后需要在程序中配置验证token。目前我们只是模拟swagger来传递header中的值。输入框输出：BearerAABBCC获取我们在Action中传输的数据vartoken=HttpContext.Request.Headers["Authorization"];image.png3参考文档https://docs.microsoft.com/zh-cn/aspnet/核心/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-5.0
