實戰篇：解決 Swagger 和自定義參數解析器的功能沖突
前情提要
看了上一篇文章看了同事寫的代碼，我竟然開始默默的模仿了。。。的小伙伴，應該已經對使用參數解析器來完成第三方接口的統一驗簽有了清晰的認識。
我們在上文中提到過，@RequestBody使用的參數解析器RequestResponseBodyMethodProcessor優先級高于我們自定義的參數解析器，所以為了正常使用，需要將@RequestBody 注解去掉。這就會導致swagger無法識別正確的參數類型，將請求體識別為Query Params，然后將body展開。
可以看到，所有參數都被識別為ModelAttribute類型(query標志)，而我們所期待的正確格式應當是如下樣子
因為該方式可以大大提高代碼的可讀性和可復用性，所以我們要知難而上，找出問題，解決問題!
問題產生的原因
產生這個問題的根本原因就是spring mvc和swagger都對@RequestBody注解進行了單獨的判定，功能上都依賴于該注解本身。
springmvc對@RequestBody注解的依賴
就拿當前自定義的參數解析器來說，如果對請求參數加上了 @RequestBody 注解，對參數的反序列化會提前被RequestResponseBodyMethodProcessor攔截，自定義的參數解析器會失效。
具體源代碼位置：https://github.com/spring-projects/spring-framework/blob/5.2.x/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestResponseBodyMethodProcessor.java#L111
可以看到，該參數解析器對加上@ReuqestBody注解的參數都支持解析，然后做序列化的操作。然而它在參數解析器列表中的優先級比較高，自定義的參數解析器添加到參數解析器列表之后會排在它的后面，所以如果加上@RequestBody注解，自定義的參數解析器就失效了。
因此使用自定義參數解析器一定不能使用@RequestBody注解
下圖源代碼位置：https://github.com/spring-projects/spring-framework/blob/5.2.x/spring-web/src/main/java/org/springframework/web/method/support/HandlerMethodArgumentResolverComposite.java#L129
此案例中用到的自定義參數解析器為HdxArgumentResolver
swagger對@Requestbody的依賴
經過調用棧追蹤，最終發現在兩個地方的功能會對@RequestBody注解有單獨判定!(感興趣的可以自行追蹤??)
- 請求類型判定：也就是說POST請求類型是哪種類型，這決定了入參是否會作為Request Parameter被展開參數，也就是文中的第一張圖，整個model都被視為ModelAttribute展開了。
- Definition屬性值填充：這確保被@RequestBody注解修飾的入參會被正常顯示，如文中第二張圖片所示。
請求類型判定
源代碼位置：https://github.com/springfox/springfox/blob/2.9.2/springfox-spring-web/src/main/java/springfox/documentation/spring/web/readers/operation/OperationParameterReader.java#L151
這里對RequestBody等常用注解進行了單獨的判定，確保這些注解修飾的入參不會被作為RequestParam展開。
Definition屬性值填充
Definition屬性中填充了入參、出參等參數類型，如果沒有相應的Model定義，則swagger信息就會是不完整的，在瀏覽器頁面中的顯示也會是不全的。填充Definition的邏輯也依賴于@RequestBody注解。
源代碼位置：https://github.com/springfox/springfox/blob/2.9.2/springfox-spring-web/src/main/java/springfox/documentation/spring/web/readers/operation/OperationModelsProvider.java#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(RetentionPolicy.RUNTIME)
- @Target({ElementType.PARAMETER})
- public @interface NoSwaggerExpand {
- /**
- * default swagger expand disable
- * @see OperationParameterReader#shouldExpand(springfox.documentation.service.ResolvedMethodParameter, com.fasterxml.classmate.ResolvedType)
- */
- 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) {
- this.expander = expander;
- this.enumTypeDeterminer = enumTypeDeterminer;
- }
- @Around("execution(* springfox.documentation.spring.web.readers.operation.OperationParameterReader.apply(..))")
- public Object pointCut(ProceedingJoinPoint point) throws Throwable {
- Object[] args = point.getArgs();
- OperationContext context = (OperationContext) args[0];
- context.operationBuilder().parameters(context.getGlobalOperationParameters());
- context.operationBuilder().parameters(readParameters(context));
- return null;
- }
- private List<parameter> readParameters(final OperationContext context) {
- List<resolvedmethodparameter> methodParameters = context.getParameters();
- List<parameter> parameters = newArrayList();
- for (ResolvedMethodParameter methodParameter : methodParameters) {
- ResolvedType alternate = context.alternateFor(methodParameter.getParameterType());
- if (!shouldIgnore(methodParameter, alternate, context.getIgnorableParameterTypes())) {
- ParameterContext parameterContext = new ParameterContext(methodParameter,
- new ParameterBuilder(),
- context.getDocumentationContext(),
- context.getGenericsNamingStrategy(),
- context);
- if (shouldExpand(methodParameter, alternate)) {
- parameters.addAll(
- expander.expand(
- new ExpansionContext("", alternate, context)));
- } else {
- parameters.add(pluginsManager.parameter(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(resolvedParameterType.getErasedType())) {
- 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 parameter.hasParameterAnnotation(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 !parameter.hasParameterAnnotation(RequestBody.class)
- && !parameter.hasParameterAnnotation(RequestPart.class)
- && !parameter.hasParameterAnnotation(RequestParam.class)
- && !parameter.hasParameterAnnotation(PathVariable.class)
- && !isBaseType(typeNameFor(resolvedParamType.getErasedType()))
- && !enumTypeDeterminer.isEnum(resolvedParamType.getErasedType())
- && !isContainerType(resolvedParamType)
- && !isMapType(resolvedParamType)
- && !noExpandAnnotaion(parameter);
- }
- private boolean noExpandAnnotaion(ResolvedMethodParameter parameter) {
- log.info("開始決定是否展開問題");
- if (!parameter.hasParameterAnnotation(NoSwaggerExpand.class)) {
- return false;
- }
- NoSwaggerExpand noSwaggerExpand = (NoSwaggerExpand) parameter.getAnnotations().stream().filter(item -> item instanceof NoSwaggerExpand).findAny().orElse(null);
- if (noSwaggerExpand.expand()) {
- return false;
- }
- return true;
- }
- }
最重要的是這里的修改
這里加上對自定義注解修飾的入參進行了判定，使得被自定義注解修飾的入參可以被Swagger當做@RequestBody一樣處理。
Definition屬性值填充的邏輯調整
再定義一個切面
- @Slf4j
- @Aspect
- @Component
- public class SwaggerDefinitionAspect {
- private static final Logger LOG = LoggerFactory.getLogger(OperationModelsProvider.class);
- private final TypeResolver typeResolver;
- @Autowired
- public SwaggerDefinitionAspect(TypeResolver typeResolver) {
- this.typeResolver = typeResolver;
- }
- @Around("execution(* springfox.documentation.spring.web.readers.operation.OperationModelsProvider.apply(..))")
- public Object pointCut(ProceedingJoinPoint point) throws Throwable {
- Object[] args = point.getArgs();
- RequestMappingContext context = (RequestMappingContext) args[0];
- collectFromReturnType(context);
- collectParameters(context);
- collectGlobalModels(context);
- return null;
- }
- private void collectGlobalModels(RequestMappingContext context) {
- for (ResolvedType each : context.getAdditionalModels()) {
- context.operationModelsBuilder().addInputParam(each);
- context.operationModelsBuilder().addReturn(each);
- }
- }
- private void collectFromReturnType(RequestMappingContext context) {
- ResolvedType modelType = context.getReturnType();
- modelType = context.alternateFor(modelType);
- LOG.debug("Adding return parameter of type {}", resolvedTypeSignature(modelType).or("<null>"));
- context.operationModelsBuilder().addReturn(modelType);
- }
- private void collectParameters(RequestMappingContext context) {
- LOG.debug("Reading parameters models for handlerMethod |{}|", context.getName());
- List<resolvedmethodparameter> parameterTypes = context.getParameters();
- for (ResolvedMethodParameter parameterType : parameterTypes) {
- if (parameterType.hasParameterAnnotation(RequestBody.class)
- || parameterType.hasParameterAnnotation(RequestPart.class)
- || parameterType.hasParameterAnnotation(NoSwaggerExpand.class)
- ) {
- ResolvedType modelType = context.alternateFor(parameterType.getParameterType());
- LOG.debug("Adding input parameter of type {}", resolvedTypeSignature(modelType).or("<null>"));
- context.operationModelsBuilder().addInputParam(modelType);
- }
- }
- LOG.debug("Finished reading parameters models for handlerMethod |{}|", context.getName());
- }
- }
在這里只改動了一處代碼，使得被自定義注解修飾的入參能夠被添加到Definition屬性中去。
做完以上兩步，即可修復springmvc獨立的參數解析器功能和swagger功能沖突的問題。
