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

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

介绍

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

本文示例环境：vs2019、net5

1 基本使用

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

image.png

1.1 安装组件

 
 
 
 
    
  
  
  
  
  1.  
    2.   
  
  
  
  2.     
    3.   
  
  
  
  3.   
    4.

1.2 注册swagger服务

在ConfigureServices中

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

注意：

//netcore3.0之前版本用法

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

1.3 使用Swagger

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

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

1.4 启动

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

image.png

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

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

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

image.png

修改注入swagger配置

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

再次启动项目查看界面

image.png

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

image.png

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

注：

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

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

2. swagger传递JWT

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

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

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

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

image.png

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

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

在输入框输出：Bearer AABBCC

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

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

image.png

3 参考文档

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

本文名称：你会.Net之Swagger基础使用吗?
文章转载：http://www.csdahua.cn/qtweb/news20/367070.html

网站建设、网络推广公司-快上网，是专注品牌与效果的网站制作，网络营销seo公司；服务项目有等

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 快上网

成都快上网为您推荐相关内容

解决方案知识

各行业网站

护栏打桩机　　 　高防服务器租用　　 　成都网络推广　　 　虚拟主机　　 　食品包装设计　　 　成都LED亮化工程　　 　成都网站推广　　 　开元建筑学校　　 　移动APP　　 　王君美油画　　 　研帮主　　 　网站营销　　 　租用服务器　　 　德阳发电机　　 　网站定制　　 　成都艾瑞格　　 　成都小程序商城　　 　企业网站设计　　 　西信中心　　 　域名申请