你会.Net之Swagger基础使用吗?

开发
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。日常可以用于后端开发人员测试接口或者前后端联调使用。

[[399419]]

本文转载自微信公众号「鹏祥」,作者AZRNG。转载本文请联系鹏祥公众号。

介绍

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。日常可以用于后端开发人员测试接口或者前后端联调使用。从.net5开始,swagger已经集成到vs2019编译器中,可以通过勾对选项“启用OpenAPI支持”显示基本的swagger配置。

本文示例环境:vs2019、net5

1 基本使用

新建一个NetCore API项目,为了测试效果,我多创建几个控制器

image.png

1.1 安装组件

  1. <ItemGroup> 
  2.    <PackageReference Include="Swashbuckle.AspNetCore" Version="5.6.3" /> 
  3.  </ItemGroup> 

 

1.2 注册swagger服务

在ConfigureServices中

  1. public void ConfigureServices(IServiceCollection services) 
  2.     services.AddControllers(); 
  3.     services.AddSwaggerGen(c => 
  4.     { 
  5.         c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi", Version = "v1" }); 
  6.     }); 

注意:

//netcore3.0之前版本用法

c.SwaggerDoc("v1", new Info { Title = "WebApi", Version = "v1" });

1.3 使用Swagger

  1. public void Configure(IApplicationBuilder app, IWebHostEnvironment env) 
  2.     if (env.IsDevelopment()) 
  3.     { 
  4.         app.UseDeveloperExceptionPage(); 
  5.         app.UseSwagger(); 
  6.         app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json""WebApi v1")); 
  7.     } 
  8.  
  9.     app.UseRouting(); 
  10.  
  11.     app.UseAuthorization(); 
  12.  
  13.     app.UseEndpoints(endpoints => 
  14.     { 
  15.         endpoints.MapControllers(); 
  16.     }); 

该示例代码配置的swagger只在Development环境下显示,可以根据实际情况来修改

1.4 启动

运行项目,展示下面的效果

image.png

如果这是你写的接口,这个时候你的其他同事去看,真的会一脸懵逼,你这写的都是啥玩意,那么我们来给这加上注释吧。

 

  1. /// <summary> 
  2. /// 用户控制器 
  3. /// </summary> 
  4. [Route("api/[controller]")] 
  5. [ApiController] 
  6. public class UserController : ControllerBase 
  7.     /// <summary> 
  8.     ///查询用户列表 
  9.     /// </summary> 
  10.     /// <returns></returns
  11.     [HttpGet] 
  12.     public IEnumerable<string> Get() 
  13.     { 
  14.         return new string[] { "value1""value2" }; 
  15.     } 
  16.  
  17.     /// <summary> 
  18.     /// 查询用户详情 
  19.     /// </summary> 
  20.     /// <param name="id"></param> 
  21.     /// <returns></returns
  22.     [HttpGet("{id}")] 
  23.     public string Get(int id) 
  24.     { 
  25.         return "value"
  26.     } 
  27.  
  28.     /// <summary> 
  29.     /// 删除用户 
  30.     /// </summary> 
  31.     /// <param name="id"></param> 
  32.     [HttpDelete("{id}")] 
  33.     public void Delete(int id) 
  34.     { 
  35.     } 

这样子加了注释还不行,swagger还读取不到我们的注释,我们还需要生成xml文档并且让swagger使用,选中项目右键属性=>生成=>xml文档文件

image.png

修改注入swagger配置

  1. services.AddSwaggerGen(c => 
  2.    { 
  3.        c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi", Version = "v1" }); 
  4.  
  5.        // 使用反射获取xml文件。并构造出文件的路径 
  6.        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"
  7.        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); 
  8.        // 启用xml注释.第二个参数启用控制器的注释,默认为false
  9.        c.IncludeXmlComments(xmlPath, true); 
  10.    }); 

再次启动项目查看界面

image.png

至此,基础的配置swagger显示注释已经实现了,那么如何调用我们接口那?

image.png

通过该界面,我们可以看到请求地址、请求方式、入参类型、输出参数等。

注:

通过设置取消显示警告:1591 , 可以去除方法和类上面的xml注释警告

如果实体类不在当前程序集下,需要同样方式配置实体类程序集的xml文档到swagger配置

2. swagger传递JWT

jwt是一个基于json的、用于在网络上声明某种主张的令牌,通常是用三部分组成:头信息,消息体,签名。他是一种双方之间传递安全信息的表述性声明规范。可以做权限验证的工具,但是目的不是为了数据加密和保护。虽然看似像是加密的数据,但是它并没有加密,不适合存储机密信息。

如果我们接口是需要传递token才可以访问,那么我们就需要对我们的swagger配置再进行改造

  1. services.AddSwaggerGen(c => 
  2.             { 
  3.                 c.SwaggerDoc("v1", new OpenApiInfo {Title = "WebApi", Version = "v1"}); 
  4.  
  5.                 // 使用反射获取xml文件。并构造出文件的路径 
  6.                 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"
  7.                 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); 
  8.                 // 启用xml注释.第二个参数启用控制器的注释,默认为false
  9.                 c.IncludeXmlComments(xmlPath, true); 
  10.  
  11.                 var security = new Dictionary<string, IEnumerable<string>> {{"Bearer", new string[] { }}}; 
  12.                 c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme() 
  13.                 { 
  14.                     Description = "JWT授权(数据将在请求头中进行传输) 在下方输入Bearer {token} 即可,注意两者之间有空格"
  15.                     Name = "Authorization", //jwt默认的参数名称 
  16.                     In = ParameterLocation.Header, //jwt默认存放Authorization信息的位置(请求头中) 
  17.                     Type = SecuritySchemeType.ApiKey, 
  18.                 }); 
  19.                 c.AddSecurityRequirement(new OpenApiSecurityRequirement 
  20.                 { 
  21.                     { 
  22.                         new OpenApiSecurityScheme 
  23.                         { 
  24.                             Reference = new OpenApiReference() 
  25.                             { 
  26.                                 Id = "Bearer"
  27.                                 Type = ReferenceType.SecurityScheme 
  28.                             } 
  29.                         }, 
  30.                         Array.Empty<string>() 
  31.                     } 
  32.                 }); 
  33.             }); 

运行,查看界面,发现界面有所不同

image.png

虽然我手上没有token,但是我也没有写校验token的代码,所以我们就暂且看为一个头部传递的工具使用。jwt具体使用后续再讲。

token传递方式就是在Headers增加 Authorization:Bearer {token} ,然后需要在程序中配置校验token,当下我们只是模拟swagger在header中传递值。

在输入框输出:Bearer AABBCC

在Action中获取我们传输的数据

  1. var token = HttpContext.Request.Headers["Authorization"]; 

image.png

3 参考文档

 

https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-5.0

 

责任编辑:武晓燕 来源: 鹏祥
相关推荐

2023-09-19 08:28:32

DiagramsPython工具

2021-08-19 15:36:09

数据备份存储备份策略

2021-09-12 17:25:12

SQLite数据库

2021-04-14 06:53:52

C# 修饰符 Public

2021-04-16 15:02:11

CAP理论分布式

2021-01-07 07:39:07

工具接口 Swagger

2024-02-22 08:31:26

数据恢复工具MySQL回滚SQL

2019-05-07 15:49:27

AI人工智能艺术

2012-06-20 10:47:25

Team Leader

2013-09-05 11:18:58

.NetWeb

2021-03-10 18:07:58

协议调试 Modbus

2010-07-13 10:40:30

唐骏

2023-06-26 08:20:02

openapi格式注解

2019-07-17 15:45:24

Spark内存Java

2011-09-30 13:37:35

51CTO博客一周热门薪酬

2022-03-25 09:39:50

LinuxLinux top

2021-11-05 10:59:06

元编程语言工具

2021-11-29 11:11:45

SQL查询技巧

2012-06-20 15:01:25

iOS开发

2023-02-27 10:45:16

点赞
收藏

51CTO技术栈公众号