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

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。日常可以用于后

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

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

介绍

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

本文示例环境:vs2019、net5

1 基本使用

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

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

image.png

1.1 安装组件

  1. <ItemGroup>
  2. <PackageReferencc f V C ~eInclude_ ] 8 C A c="Swashbuckle.AspNetCore"Version="5.6.3"/>
  3. </ItemGa - y lroup>

1.2 注册swagger服务

V b g | 1 : QConfigureServices中

  1. pu2 g sblicvoidConfigureServices(IServiceCollectionservices)
  2. {
  3. services.AddControllerq v ~ +s();y P c .
  4. services^ v ~ 5.AddSwaggerx ` ^ V W P * p WGen(c=>
  5. {
  6. c.SwaggerDoc("v1",newOpenApiInfo{Title="WebApi",VerB V ~ : M bsion="v1"});
  7. });
  8. }

注意:S 0 `

//netcore3.0之前版本用法

c.l w Z % j L T !SwaggerDoc(“v1”, new Info { Title = “WebApi”, Version = “v1” });

1.3 使用Swagger

  1. pu\ x z & : l I JblicvoidConfigure(IApplicationBuilderapp,IWebHostEnvironmentenv)v y Q + & y
  2. {
  3. if(env.IsDevelopment())
  4. {
  5. app.UseDB x 1 t 9 [ X N [evelop/ x # KerExceptionP. p X 6 8 8 = } Mage();
  6. app.UseSwagger();
  7. app.UseSwaggerUI(c=>c.SwaggerEndpoint("/swagger/v1/swagger.json[ u ^ \ / [ - L","WebApiv1"));
  8. }
  9. app.UseRouting();
  10. app.UseAuthorization();
  11. app.UseEndpoints(endpoints=>
  12. {
  13. endpoints.MapCW / O ^ Y 2 5 Bon\ e : & L 5 ! atrollers();
  14. });
  15. }

% 6 [ c r n w 3示例代码配置的swagger只在Development环境下显示,可以根据实际情况来修改

1.4 启动

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

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

image.png

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

  1. ///<summary>
  2. ///用户控制器
  3. ///</summary>
  4. [Route("api/[controller]")]
  5. [ApiController]
  6. publ 7 rliccl# i / Q r } * AassUserController:ControllerBase
  7. {
  8. ///<summary>
  9. ///查询用户列表
  10. ///</summary>
  11. ///&l* Y [ N G a Gt;returns></returns>
  12. [HttpGet]
  13. publicIEnumerable<string>Get()
  14. {
  15. returnneB 5 a 5wstring[]{"value1","value2"};
  16. }
  17. ///<summary>
  18. ///查询用户详情
  19. ///</summary>
  20. ///<paramname="id"></param>
  21. ///<returns></returns>
  22. [HttpGet("{id}")]
  23. publicstringGet(inB s @ p } Ntid)
  24. {
  25. return"value";
  26. }
  27. ///<summary>
  28. ///删除用户
  29. ///</summary>
  30. //e 7 \/<paramname="id">6 s n # : @ G ^ Q</param>
  31. [HttpDelete("{id}")]
  32. publicvoidDele? q = t B 4 c 8 Vte(in# t $ ? ` R ati^ 6 K 0 P F a ?d)
  33. {
  34. }
  35. }

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

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

image.png

修改注入swagger配置

  1. services.AddSwaggerGen(c=>
  2. {
  3. c.SwaggerDoc("v1",ne, $ WwOpenApii T A pInfo{Title="WebApi",Version="v1"});
  4. //使用反射获取xml文件。并构造出文件的路径
  5. varxmlFile=$"{Assembly.GetExecutingAssembly().GM w A B 0 R ; ] XetName().Name}.L Y { o p 2xml";
  6. varxmn v GlPath=K 0 T 7 p i 4 vPath.Ce q / m \ F 2 kombine(AppContext.BaseDirectory,xmlFile);
  7. //启用xml注p ! [ E释.第二个参数启用控制器的注释,默认为false.
  8. c.IncludeXmlComments(xmlPath,true);
  9. });

再次启动项目查看界面

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

image.png

至此,基础的配置sm F 5 r n _waggs \ * N S ser显示注释已经实现了,那么如何调用我们接口那?

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

image.png

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

注:

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

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

2. swagger传递JWT

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

如果我们接口是需要传递tokenl J + E ; o 9 + ]才可以访问,那么我们就需要对V y X h n K O 4 y我们的swagger配) , b a } & r置再进行改造

  1. serr O , / H } svices.A= m z v /ddSwaggerGen(c=>
  2. {
  3. c.SwaggerDoc("v1",new5 F Y cOpenApiInfo{Title="WebApi",Version="v1"});
  4. //使用反射获取xml文件。并构造出文件的路径
  5. varxmlFile3 h @ w=$"{Assembly.GZ F 5 ? o ketExecutingAssemblE + ay().GetName().Name}.xml";
  6. varxmlPaP C d 5th=Path.CombineP Y b 6 i 2 x U(AppContV ( $ ] G X B % jext.BaseDirecto3 & = O f ; rry,xmlFile);
  7. //启用xml注释.第二个参数启用控制器的注释,默认为false.
  8. c.InN : ) ` j O @cludeXmlComments(xmlPath,true);
  9. varsecurity=newDi8 ( M ( D ,ctionary<string,IEnum~ ) o W } u @ Herable<string>>{{"Beau t { V ! ,rer",newstring[]{}}};
  10. c.Add@ b ; & 7 8SecurityDefinition("Bearer",newOpenApiSe? ; / %curityScheme()
  11. {
  12. DeW h 8 { c Wscription="JWT授权(数据将在请求头中进行传输)在下方输入Bearer{token}即可,注意两者之间有空格",
  13. Name="Authorization",//jwt默认的参数名称
  14. In=ParameterLocation.Header,//jwt默认存放Authorization信息的位置(请求头中)
  15. Type=SecuritySchemeType.ApiKey,
  16. });
  17. c.AddSecurityRequirement(newOp2 \ $enApiSecurityRequirement
  18. {
  19. {
  20. newOpenApiSecurityScheme
  21. {
  22. Reference=newOpenApiRefe$ # t p w 1 $ 7 Urencg 1 i |e()
  23. {
  24. Id="Bea7 t 8 t ( w 5 % !rer",
  25. Type=ReferenceType.Securit7 u $ O [yScheme
  26. }
  27. },
  28. Array.Empty<string>()
  29. }
  30. });
  31. });

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

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

image.png

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

token传递方式就是在Headers增加 Authorization:Bearer {token} ,然后v ~ J H $ f &需要在程序中配置校– v / T验token,当下我们只是模拟swagg9 – 3 D Ser在header中传递值。

在输入框输出:Bearer AABBCC

在Action中获取我们传输的4 E k V数据

  1. vartoken=HttpContext.Request.Headers["Authorization"];

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

image.png

3 参考文档

https://docs.micS H s |rosoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?vi– \ p 8ew=aspnetcore-5.0

上一篇 2021年5月15日 下午10:52
下一篇 2021年5月15日 下午10:52