实战篇：解决swagger和自定义参数解析器的功能冲突

前言

@RequestBody使用的参数解析器RequestResponseBodyMethodProcessor优先级高于我们自定义的参数解析器，所以为了正常使用，需要将@RequestBody 注解去掉。这就会导致swagger无法识别正确的参数类型，将请求体识别为Query Params，然后将body展开。

 

可以看到，所有参数都被识别为ModelAttribute类型（query标志），而我们所期待的正确格式应当是如下样子

因为该方式可以大大提高代码的可读性和可复用性，所以我们要知难而上，找出问题，解决问题！

问题产生的原因

产生这个问题的根本原因就是spring mvc和swagger都对@RequestBody注解进行了单独的判定，功能上都依赖于该注解本身。

springmvc对@RequestBody注解的依赖

就拿当前自定义的参数解析器来说，如果对请求参数加上了 @RequestBody 注解，对参数的反序列化会提前被RequestResponseBodyMethodProcessor拦截，自定义的参数解析器会失效。

具体源代码位置：/spring-projects/spring-framework/blob/5./spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/#L111

可以看到，该参数解析器对加上@ReuqestBody注解的参数都支持解析，然后做序列化的操作。然而它在参数解析器列表中的优先级比较高，自定义的参数解析器添加到参数解析器列表之后会排在它的后面，所以如果加上@RequestBody注解，自定义的参数解析器就失效了。

因此使用自定义参数解析器一定不能使用@RequestBody注解

下图源代码位置：/spring-projects/spring-framework/blob/5./spring-web/src/main/java/org/springframework/web/method/support/#L129

此案例中用到的自定义参数解析器为HdxArgumentResolver

swagger对@Requestbody的依赖

经过调用栈追踪，最终发现在两个地方的功能会对@RequestBody注解有单独判定！（感兴趣的可以自行追踪????）

• 请求类型判定：也就是说POST请求类型是哪种类型，这决定了入参是否会作为Request Parameter被展开参数，也就是文中的第一张图，整个model都被视为ModelAttribute展开了。

• Definition属性值填充：这确保被@RequestBody注解修饰的入参会被正常显示，如文中第二张图片所示。

请求类型判定

源代码位置：/springfox/springfox/blob/2.9.2/springfox-spring-web/src/main/java/springfox/documentation/spring/web/readers/operation/#L151

这里对RequestBody等常用注解进行了单独的判定，确保这些注解修饰的入参不会被作为RequestParam展开。

Definition属性值填充

Definition属性中填充了入参、出参等参数类型，如果没有相应的Model定义，则swagger信息就会是不完整的，在浏览器页面中的显示也会是不全的。填充Definition的逻辑也依赖于@RequestBody注解。

源代码位置：/springfox/springfox/blob/2.9.2/springfox-spring-web/src/main/java/springfox/documentation/spring/web/readers/operation/#L80

可以看到，只有被RequestBody注解和RequestPart注解修饰的入参才会被接收进入Definition属性。

综合以上两张图的源代码分析，可以看到，swagger功能依赖于@RequestBody注解，入参如果不被该注解修饰，则swagger功能就会不完整，这和在springmvc中使用独立的参数解析器功能不得使用@RequestBody注解矛盾。

解决问题

从以上分析可以得到结论，这里的根本问题是springmvc中独立的参数解析器功能和swagger功能上的冲突，一个要求不能加上@RequestBody注解，一个要求必须加上@RequestBody注解，所以解决方法上可以使用两种方式

• 从springmvc入手，想办法提高自定义参数解析器的优先级，只要自定义的参数解析器优先级比RequestResponseBodyMethodProcessor高，则就可以在自定义的参数上加上@RequestBody注解，swagger功能自然而然就能正常了。

• 从swagger入手，想办法解决掉上面两部分对@RequestBody的单独判定，不修改springmvc相关功能也可以让swagger功能正常。

考虑到修改springmvc功能可能会对以后的版本升级造成较大影响，这里决定利用切面修改原有的swagger对@RequestBody的两个地方的行为，从而让swagger功能正常。

请求类型判定的逻辑调整

首先，定义一个注解

@Documented




@Retention()




@Target({})



public @interface NoSwaggerExpand {



 



    /**




     * default swagger expand disable



     * @see OperationParameterReader#shouldExpand(, )



     */



    boolean expand() default false;



}

将其加到入参上

    @ApiOperation(value = "demo", notes = "demo")



    @PostMapping(value = "/test")



    public Result<boolean> test(@HdxDecrypt @NoSwaggerExpand @ApiParam(required = true) ReqDTO reqDTO) {



        try {



            log.info(ObjectMapperFactory.getObjectMapper().writeValueAsString(reqDTO));



        } catch (JsonProcessingException e) {



            log.error("", e);



        }



        return null;



    }

然后定义切面

@Slf4j



@Aspect



@Component



public class SwaggerExpandAspect {



 



    private final ModelAttributeParameterExpander expander;



    private final EnumTypeDeterminer enumTypeDeterminer;



 



    @Autowired



    private DocumentationPluginsManager pluginsManager;



 



    @Autowired



    public SwaggerExpandAspect(



            ModelAttributeParameterExpander expander,



            EnumTypeDeterminer enumTypeDeterminer) {



         = expander;



         = enumTypeDeterminer;



    }



 



    @Around("execution(* (..))")



    public Object pointCut(ProceedingJoinPoint point) throws Throwable {



        Object[] args = ();



        OperationContext context = (OperationContext) args[0];



        ().parameters(());



        ().parameters(readParameters(context));



        return null;



    }



 



    private List<parameter> readParameters(final OperationContext context) {



 



        List<resolvedmethodparameter> methodParameters = ();



        List<parameter> parameters = newArrayList();



 



        for (ResolvedMethodParameter methodParameter : methodParameters) {



            ResolvedType alternate = (());



            if (!shouldIgnore(methodParameter, alternate, ())) {



 



                ParameterContext parameterContext = new ParameterContext(methodParameter,



                        new ParameterBuilder(),



                        (),



                        (),



                        context);



 



                if (shouldExpand(methodParameter, alternate)) {



                    (



                            (



                                    new ExpansionContext("", alternate, context)));



                } else {



                    parameters.add((parameterContext));



                }



            }



        }



        return FluentIterable.from(parameters).filter(not(hiddenParams())).toList();



    }



 



 



    private Predicate<parameter> hiddenParams() {



        return new Predicate<parameter>() {



            @Override




            public boolean apply(Parameter input) {



                return input.isHidden();



            }



        };



    }



 



    private boolean shouldIgnore(



            final ResolvedMethodParameter parameter,



            ResolvedType resolvedParameterType,



            final Set<class> ignorableParamTypes) {



 



        if (ignorableParamTypes.contains(())) {



            return true;



        }



        return FluentIterable.from(ignorableParamTypes)



                .filter(isAnnotation())



                .filter(parameterIsAnnotatedWithIt(parameter)).size() > 0;



 



    }



 



    private Predicate<class> parameterIsAnnotatedWithIt(final ResolvedMethodParameter parameter) {



        return new Predicate<class>() {



            @Override




            public boolean apply(Class input) {



                return (input);



            }



        };



    }



 



    private Predicate<class> isAnnotation() {



        return new Predicate<class>() {



            @Override




            public boolean apply(Class input) {



                return Annotation.class.isAssignableFrom(input);



            }



        };



    }



 



    private boolean shouldExpand(final ResolvedMethodParameter parameter, ResolvedType resolvedParamType) {



        return !(RequestBody.class)



                && !(RequestPart.class)



                && !(RequestParam.class)



                && !(PathVariable.class)



                && !isBaseType(typeNameFor(()))



                && !(())



                && !isContainerType(resolvedParamType)



                && !isMapType(resolvedParamType)



                && !noExpandAnnotaion(parameter);



 



    }



 



    private boolean noExpandAnnotaion(ResolvedMethodParameter parameter) {



        ("开始决定是否展开问题");



        if (!(NoSwaggerExpand.class)) {



            return false;



        }



        NoSwaggerExpand noSwaggerExpand = (NoSwaggerExpand) ().stream().filter(item -> item instanceof NoSwaggerExpand).findAny().orElse(null);



        if (()) {



            return false;



        }



        return true;



    }



 



}

最重要的是这里的修改

这里加上对自定义注解修饰的入参进行了判定，使得被自定义注解修饰的入参可以被Swagger当做@RequestBody一样处理。

Definition属性值填充的逻辑调整

再定义一个切面

@Slf4j



@Aspect



@Component




public class SwaggerDefinitionAspect {



 



    private static final Logger LOG = ();



    private final TypeResolver typeResolver;



 



    @Autowired




    public SwaggerDefinitionAspect(TypeResolver typeResolver) {



        this.typeResolver = typeResolver;



    }



 



    



    @Around("execution(* (..))")




    public Object pointCut(ProceedingJoinPoint point) throws Throwable {



        Object[] args = ();



        RequestMappingContext context = (RequestMappingContext) args[0];



        collectFromReturnType(context);



        collectParameters(context);



        collectGlobalModels(context);



        return null;



    }



    



    private void collectGlobalModels(RequestMappingContext context) {



        for (ResolvedType each : ()) {



            ().addInputParam(each);



            ().addReturn(each);



        }



    }



 



    private void collectFromReturnType(RequestMappingContext context) {



        ResolvedType modelType = ();



        modelType = (modelType);



        ("Adding return parameter of type {}", resolvedTypeSignature(modelType).or("<null>"));



        ().addReturn(modelType);



    }



 



    private void collectParameters(RequestMappingContext context) {



 



 



        ("Reading parameters models for handlerMethod |{}|", ());



 



        List<resolvedmethodparameter> parameterTypes = ();



        for (ResolvedMethodParameter parameterType : parameterTypes) {



            if (()



                    || ()



            || ()



            ) {



                ResolvedType modelType = (());



                ("Adding input parameter of type {}", resolvedTypeSignature(modelType).or("<null>"));



                ().addInputParam(modelType);



            }



        }



        ("Finished reading parameters models for handlerMethod |{}|", ());



    }



}

在这里只改动了一处代码，使得被自定义注解修饰的入参能够被添加到Definition属性中去。

做完以上两步，即可修复springmvc独立的参数解析器功能和swagger功能冲突的问题。

原文地址：实战篇：解决swagger和自定义参数解析器的功能冲突

如果觉得本文对你有帮助，麻烦点赞转发加关注支持一下