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

介绍

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

本文示例环境:vs2019、net5

1 基本使用

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

image.png

1.1 安装组件

  1. <ItemGroup>
  2. <PackageReferenceInclude="Swashbuckle.AspNetCore"x { ] e H t y 0Version="5.6.3"/>
  3. </ItemGroup>

1.2 注册swagger服务

在Config| a : $ \ureService: S / 0 – & * 3 xs中

  1. publicvoidConfigureServices(IServick \ t w [ , 6 \eCollectionservices)
  2. {
  3. services.AddControllers();
  4. services.AddSwaggerG 8 4 ) * } ,Gen(c=>
  5. {
  6. c.SwaggerDoc("v1",newOpt H x h O f F p 2enApiIG 5 E R v 5nfo{Title="WebApi",Version="v1"});
  7. });
  8. }

注意:

//7 I 4 p ^netcore3.0之前版本用法

c.SwaggerDoc(“v1”, new Ix V R ) p O @nfo { Title = “WebApi”, Version = “v1” });

1.3 使用Swagger

  1. publicvoidConfigure(IApplicationBuil& w x v R Sderapp,IWebHostEnvironmentenv)/ O e 3
  2. {
  3. if(env.IsDevelopment())
  4. {
  5. app.UseDeveloperExceptionPage();
  6. app.UseSwagger();
  7. app.UseSwaggerUI(5 r Z q :c=>c.Swagge& R A U 7 d l d /rEndpoint("/s4 N 4 ^ H k ) 0 Swagger/v1/swagger.json","WebApiv1"));
  8. }
  9. app.UseRouting();
  10. app.UseAuthorization()@ M Q C } f - h _;
  11. app.UseEndpoints(endpoints=>
  12. {w } . V r R
  13. endpoints.Ma) A d 4 @pControllers();
  14. });
  15. }

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

1.4 启动

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

image.png

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

  1. ///<summary>
  2. ///用户控制器
  3. ///</summary>
  4. [Route("api/[controller]")]
  5. [ApiController]
  6. publicclassUserController:ControllerBase
  7. {
  8. ///&x C c F = Blt;summar} d X %y>
  9. ///查询用户列表
  10. ///</summary>
  11. ///<returns></returns>
  12. [HttpGet]
  13. publicIEnumerable<st+ b B ^ $ ] fring>GetO E I * T w V 6()
  14. {
  15. returnnewstring[]{"value1","value2"};
  16. }
  17. ///<summary>
  18. ///查询用户详情
  19. ///</summary>
  20. ///[ i 2 Z<b J } | j ` 5;paramname="id"></param>
  21. ///<returns></returns>
  22. [HttpGet("{id}")]
  23. publicstringGet(intid)
  24. {
  25. return"value";
  26. }
  27. ///<T 8 2;summary>
  28. ///删除用户
  29. ///</summa` d 0ry>
  30. ///<paramname="id"></param>
  31. [HttpDelete("{id}")]
  32. publicvoidDu = \ S H Q Qelete(intid)
  33. {
  34. }
  35. }

这样子加了d O 7 \ m ? }注释还不行,s1 [ ?wagger还读取不到我们的注T ] P C : 7 1 O 5释,我们还需c l O g要生成xml文档并且让swagger使用,选中项目右键属性=>生成=>xml文档文件

ima, ? q \ge.png

修改注入swagger配置

  1. services.AddSwaggerGen(c=>
  2. {
  3. c.SwaggerDoc("v1",ne6 6 % 0 ( 6 - j ZwOpenApiInfo{Title="WebApi",Version="v1"});
  4. //使用反射获取xm, f O 4 n K c 3 Yl文件。并构造出文件的路径
  5. varxmlFile=$"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
  6. varxmlPath=Path.Combine(AppContext.BaseDirectory,xmlFile);
  7. //启用xml注释.第二个参数启用控制( % } D O k 0器的注释,默认为false.s P Z U
  8. c.IncludeXmlComments(xmlPath,true);
  9. });

再次启动项目查看界面K @ } – w

image.png

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

image.png

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

注:

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

– 1 d U e } ! T r果实体类不在当前程序集下,需要同样方式配置实体类程序集的xml文档到swagger配置

2. swagger传递JWT

jwt是一个基于json的、用于在网络上声明某种主张的令牌,通常是用三部分组成:头信息,消息体,签名。他是一种双方之间传递安全信8 L . $ = Z D A息的表述e Q $性声明规范。可以做权限验证的工具,但是目的不是为了数据加密和I Y m P v保护。虽8 . / z X ` – H然看似像是加密的数据,但是@ \ K w它并没有加密,不适f C u w \ N合存储机密信息。

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

  1. sn D ? S Dervices.AddSwaggerGen(c=>
  2. {
  3. c.SwaggerDoc("v1",newOpenApiInfo{Title="WebApi",Ve7 v J N | 8 1 T @rsion="v1"});
  4. //使用反射获取xml文4 D }件。并构造出文件^ M R 8 W 4 i 3 :的路径
  5. varxmlFile=$"{Assembly.GetExecutingAssembly().GetName(W C c ;).Name}.xml";
  6. varxmlPath=Path.Combin) | ~e(AppContext.BaseDirectory,xmlFile);
  7. //启用xml注释.第二个参数启用控制器的注释,默认为false.
  8. c.IncludeXmlComments(xmlPai a 5 Nth,true);
  9. varsecurity=newDictionary<string,IEnumerable&l| P n _ g \t;string>>{{"Bearer",newstriQ c ; ^ % { Q &ng[]{}}};
  10. c.AddSecurityDefinition("Bearer",newOpenApiSecurityScheme()
  11. {
  12. Descric a ) u n [ y pption="JWT授权(数据将在请求头中进行传输)在下方输入Bearer{token}即可,注意两者之间有空格",
  13. Name="Authorization",//jwt默认的参数名称
  14. In=ParameterLocation.Header,//jwt默认存放Authorization信息的位置(请求头中)
  15. Type=SecuritySchemeType.ApiKey,
  16. });
  17. c.AddSecurityRequirement(newOpenApiSecurit\ ( I b \ 1yRequirement
  18. {
  19. {
  20. newOpenApiSecurityScheme
  21. {
  22. Reference=newOpenApiReference()
  23. {
  24. Ic f b \ # 3 !d="Bearer",
  25. Type) , i ! +=ReferenceType.SecurityScheme
  26. }
  27. },
  28. Array.Empty<string>()
  29. }
  30. });
  31. });

运行,查看界面,发现o , ` \ * e ( ; v界面有所不同

image.png

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

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

在输入框输出:Bearer AABBCC

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

  1. va@ O Ertoken=HttpContext.Request.Headers["Authorization"];

image.png

3 参考文档

https://docs.microsoft.com/zh-cn/aspnet/core/+ f * Q * ) l P Qtutorials/web-api-help-pages-using-swagger?vi8 g qew=aspnetcore-5.0

发表评论

您的电子邮箱地址不会被公开。 必填项已用*标注