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

本文转载自微信公众号「鹏祥」，作者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 安装组件

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

1.2 注册swagger服务

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

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

注意：

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

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

1.3 使用Swagger

publicvoidConfigure(IApplicationBuil& w x v R Sderapp,IWebHostEnvironmentenv)/ O e 3
{
if(env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseSwagger();
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"));
}

app.UseRouting();

app.UseAuthorization()@ M Q C } f - h _;

app.UseEndpoints(endpoints=>
{w } . V r R
endpoints.Ma) A d 4 @pControllers();
});
}

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

1.4 启动

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

image.png

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

///<summary>
///用户控制器
///</summary>
[Route("api/[controller]")]
[ApiController]
publicclassUserController:ControllerBase
{
///&x C c F = Blt;summar} d X %y>
///查询用户列表
///</summary>
///<returns></returns>
[HttpGet]
publicIEnumerable<st+ b B ^ $ ] fring>GetO E I * T w V 6()
{
returnnewstring[]{"value1","value2"};
}

///<summary>
///查询用户详情
///</summary>
///[ i 2 Z<b J } | j ` 5;paramname="id"></param>
///<returns></returns>
[HttpGet("{id}")]
publicstringGet(intid)
{
return"value";
}

///<T 8 2;summary>
///删除用户
///</summa` d 0ry>
///<paramname="id"></param>
[HttpDelete("{id}")]
publicvoidDu = \ S H Q Qelete(intid)
{
}
}

这样子加了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配置

services.AddSwaggerGen(c=>
{
c.SwaggerDoc("v1",ne6 6 % 0 ( 6 - j ZwOpenApiInfo{Title="WebApi",Version="v1"});

//使用反射获取xm, f O 4 n K c 3 Yl文件。并构造出文件的路径
varxmlFile=$"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
varxmlPath=Path.Combine(AppContext.BaseDirectory,xmlFile);
//启用xml注释.第二个参数启用控制( % } D O k 0器的注释，默认为false.s P Z U
c.IncludeXmlComments(xmlPath,true);
});

再次启动项目查看界面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配置再进行改造

sn D ? S Dervices.AddSwaggerGen(c=>
{
c.SwaggerDoc("v1",newOpenApiInfo{Title="WebApi",Ve7 v J N | 8 1 T @rsion="v1"});

//使用反射获取xml文4 D }件。并构造出文件^ M R 8 W 4 i 3 :的路径
varxmlFile=$"{Assembly.GetExecutingAssembly().GetName(W C c ;).Name}.xml";
varxmlPath=Path.Combin) | ~e(AppContext.BaseDirectory,xmlFile);
//启用xml注释.第二个参数启用控制器的注释，默认为false.
c.IncludeXmlComments(xmlPai a 5 Nth,true);

varsecurity=newDictionary<string,IEnumerable&l| P n _ g \t;string>>{{"Bearer",newstriQ c ; ^ % { Q &ng[]{}}};
c.AddSecurityDefinition("Bearer",newOpenApiSecurityScheme()
{
Descric a ) u n [ y pption="JWT授权(数据将在请求头中进行传输)在下方输入Bearer{token}即可，注意两者之间有空格",
Name="Authorization",//jwt默认的参数名称
In=ParameterLocation.Header,//jwt默认存放Authorization信息的位置(请求头中)
Type=SecuritySchemeType.ApiKey,
});
c.AddSecurityRequirement(newOpenApiSecurit\ ( I b \ 1yRequirement
{
{
newOpenApiSecurityScheme
{
Reference=newOpenApiReference()
{
Ic f b \ # 3 !d="Bearer",
Type) , i ! +=ReferenceType.SecurityScheme
}
},
Array.Empty<string>()
}
});
});

运行，查看界面，发现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中获取我们传输的数据

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

‭

链接