从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之十二Swagger(参数)使用二
引言
在 中提到了 swagger 的基本使用,仅限于没有参数,没有验证的那种api文档生成,那么这篇就连接上篇继续,在一般具有安全性、权限等验证的接口上,
都会在header/url中加上请求者的秘钥、签名等,当然也有可能添加到body等其它地方, swashbuckle.aspnetcore 都支持这些写法。
如何使用 -- 下面将介绍两种使用方式
两种方式参数设置到何处都是在 in属性上,属性对于值如下: 参考 https://github.com/oai/openapi-specification/blob/master/versions/2.0.md#parameter-object
- query: 参数字段值对应放在url中
- header: 参数值对应放在header param中
- body: 参数对应放到请求体中
- path: 参数应该对应放到请求路径 // 具体貌似没用
- formdata: 参数对应放到请求表单中
第一种:将一个或多个参数保护api的“securitydefinitions”添加到生成的swagger中。
这种是直接在文档的右上方添加一个 authorize 按钮,设置了值后,每一个请求都会在设置的位置上加上相应的值,在 上一篇随笔中的 configureservices 方法中,
对应位置 services.addswaggergen(options =>{}) 中的 xmlcomments 下 添加代码如下:
options.addsecuritydefinition("token", new apikeyscheme { description = "token format : {token}",//参数描述 name = "token",//名字 in = "header",//对应位置 type = "apikey"//类型描述 }); options.addsecuritydefinition("sid", new apikeyscheme { description = "sid format : {sid}",//参数描述 name = "sid",//名字 in = "header",//对应位置 type = "apikey"//类型描述 }); //添加jwt验证设置 设置为全局的,不然在代码中取不到 options.addsecurityrequirement(new dictionary<string, ienumerable<string>> { { "token", enumerable.empty<string>() }, { "sid", enumerable.empty<string>() }, });
添加完成后,运行起来看下效果,效果图:
设置上对应值,调用测试方法,可以在header中取到刚设置到的值,
这里能看到,可以取到设置的参数了。这样一来,在需要验证的接口上,我们就可以通过接口文档来测试了。基本不用再借助postman等接口测试工具了。
但是,但是,这里有一个问题,就是只要设置了参数值,每一次访问都会在请求中带上参数。
下面将介绍第二种方式,只给需要验证用户的接口上添加验证参数。
第二种:使用“filters”扩展swagger生成器,来实现只在需要添加参数的方法上添加参数。复杂的可以根据自己的需求来添加对应参数
实现方式就是先新建一个类,名: swaggerparameter ,实现 ioperationfilter 接口。swaggerparameter 类代码如下:
/// <summary> /// 自定义添加参数 /// </summary> public class swaggerparameter : ioperationfilter { /// <summary> /// 实现 apply 方法 /// </summary> /// <param name="operation"></param> /// <param name="context"></param> public void apply(operation operation, operationfiltercontext context) { if (operation.parameters == null) operation.parameters = new list<iparameter>(); var attrs = context.apidescription.actiondescriptor.attributerouteinfo; var t = typeof(baseusercontroller); //先判断是否是继承用户验证类 if (context.apidescription.actiondescriptor is controlleractiondescriptor descriptor && context.methodinfo.declaringtype?.issubclassof(t) == true) { //再验证是否允许匿名访问 var actionattributes = descriptor.methodinfo.getcustomattributes(inherit: true); bool isanonymous = actionattributes.any(a => a is allowanonymousattribute); // 需要验证的方法添加 if (!isanonymous) { operation.parameters.add(new nonbodyparameter() { name = "sid", in = "header", //query header body path formdata type = "string", required = true,//是否必选 description = "登录返回的sid" }); operation.parameters.add(new nonbodyparameter() { name = "token", in = "header", //query header body path formdata type = "string", required = true,//是否必选 description = "登录返回的token" }); } } } }
运行起来后,进入到 文档页面,可以看到右上角的 authorize 按钮已经不见了,在不需要验证的方法上,也找不到相应需要设置参数的输入框。就只有在需要验证的接口上才有。
参考swagger文档图如下:
参考代码图如下:
效果图:
这样一来设置也就完成了。从上面就能看出,就只有需要用户验证的接口才会有相应参数。
我的设置方式是先定义了用户验证控制器类,让需要用户验证的控制器继承该控制器,然后在该控制器中不需要用户验证的接口上加上 allowanonymous 属性
设置fitter时就可以根据上面提到的两个点来进行判断是否需要加上参数,如果不是这样实现的,可以根据自己的需求变更fitter类,来控制文档的生成。
以上若有什么不对或可以改进的地方,望各位指出或提出意见,一起探讨学习~
有需要源码的可通过此 github 链接拉取 觉得还可以的给个 start 和点个 下方的推荐哦~~谢谢!
推荐阅读
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之七使用JWT生成Token(个人见解)
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之十一Swagger使用一
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之十数据库基础方法的封装
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之九如何进行用户权限控制
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之六使用过滤器进行全局请求数据验证
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之八MemoryCache与redis缓存的使用
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之十一Swagger使用一
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之七使用JWT生成Token(个人见解)
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之十二Swagger(参数)使用二
-
从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之十数据库基础方法的封装