从零开始搭建前后端分离的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的项目框架之十二Swagger(参数)使用二

时间:2024-01-25 22:14:13

  引言

  在 上一篇 中提到了 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"
                    });
                }
            }
        }
    }

 

运行起来后,进入到 https://localhost:5001/apidoc/index.html 文档页面,可以看到右上角的 Authorize 按钮已经不见了,在不需要验证的方法上,也找不到相应需要设置参数的输入框。就只有在需要验证的接口上才有。

参考Swagger文档图如下:

 

参考代码图如下:

 

 效果图:

 

 

 

这样一来设置也就完成了。从上面就能看出,就只有需要用户验证的接口才会有相应参数。

 

 

 

我的设置方式是先定义了用户验证控制器类,让需要用户验证的控制器继承该控制器,然后在该控制器中不需要用户验证的接口上加上 AllowAnonymous 属性

 

设置fitter时就可以根据上面提到的两个点来进行判断是否需要加上参数,如果不是这样实现的,可以根据自己的需求变更fitter类,来控制文档的生成。

 

 

 

 

以上若有什么不对或可以改进的地方,望各位指出或提出意见,一起探讨学习~

 

有需要源码的可通过此 GitHub 链接拉取 觉得还可以的给个 start 和点个 下方的推荐哦~~谢谢!