spring fox swagger 2.7.0 框架 ApiModelProperty name别名映射field不生效解决方案

大家好，欢迎来到IT知识分享网。

1、关于swagger提供的ApiModelProperty 提供的注解。ApiModelProperty 标注在对象中的field 上。使用ApiModelProperty 注解中的name属性给字段取别名不生效的产生原因。根据swagger 解析ApiModelProperty 注解的源码可以发现 swagger 并没有把ApiModelProperty 中的name 替换成实体类的字段name。具体可以看swagger的源码 核心类SwaggerExpandedParameterBuilder 如下

public class SwaggerExpandedParameterBuilder implements ExpandedParameterBuilderPlugin { 
   
    private final DescriptionResolver descriptions;

    @Autowired
    public SwaggerExpandedParameterBuilder(DescriptionResolver descriptions) { 
   
        this.descriptions = descriptions;
    }

    public void apply(ParameterExpansionContext context) { 
   
        Optional<ApiModelProperty> apiModelPropertyOptional = ApiModelProperties.findApiModePropertyAnnotation((AnnotatedElement)context.getField().getRawMember());
        if (apiModelPropertyOptional.isPresent()) { 
   
            this.fromApiModelProperty(context, (ApiModelProperty)apiModelPropertyOptional.get());
        }

        Optional<ApiParam> apiParamOptional = Annotations.findApiParamAnnotation((AnnotatedElement)context.getField().getRawMember());
        if (apiParamOptional.isPresent()) { 
   
            this.fromApiParam(context, (ApiParam)apiParamOptional.get());
        }

    }

    public boolean supports(DocumentationType delimiter) { 
   
        return SwaggerPluginSupport.pluginDoesApply(delimiter);
    }

    private void fromApiParam(ParameterExpansionContext context, ApiParam apiParam) { 
   
        String allowableProperty = Strings.emptyToNull(apiParam.allowableValues());
        AllowableValues allowable = this.allowableValues(Optional.fromNullable(allowableProperty), (Field)context.getField().getRawMember());
        context.getParameterBuilder().description(this.descriptions.resolve(apiParam.value())).defaultValue(apiParam.defaultValue()).required(apiParam.required()).allowMultiple(apiParam.allowMultiple()).allowableValues(allowable).parameterAccess(apiParam.access()).hidden(apiParam.hidden()).build();
    }

    private void fromApiModelProperty(ParameterExpansionContext context, ApiModelProperty apiModelProperty) { 
   
        String allowableProperty = Strings.emptyToNull(apiModelProperty.allowableValues());
        AllowableValues allowable = this.allowableValues(Optional.fromNullable(allowableProperty), (Field)context.getField().getRawMember());
        context.getParameterBuilder().description(this.descriptions.resolve(apiModelProperty.value())).required(apiModelProperty.required()).allowableValues(allowable).parameterAccess(apiModelProperty.access()).hidden(apiModelProperty.hidden()).build();
    }

    private AllowableValues allowableValues(Optional<String> optionalAllowable, Field field) { 
   
        AllowableValues allowable = null;
        if (field.getType().isEnum()) { 
   
            allowable = new AllowableListValues(this.getEnumValues(field.getType()), "LIST");
        } else if (optionalAllowable.isPresent()) { 
   
            allowable = ApiModelProperties.allowableValueFromString((String)optionalAllowable.get());
        }

        return (AllowableValues)allowable;
    }

    private List<String> getEnumValues(Class<?> subject) { 
   
        return Lists.transform(Arrays.asList(subject.getEnumConstants()), new Function<Object, String>() { 
   
            public String apply(Object input) { 
   
                return input.toString();
            }
        });
    }
}

2、具体的构建swagger 参数代码如下

private void fromApiModelProperty(ParameterExpansionContext context, ApiModelProperty apiModelProperty) { 
   
        String allowableProperty = Strings.emptyToNull(apiModelProperty.allowableValues());
        AllowableValues allowable = this.allowableValues(Optional.fromNullable(allowableProperty), (Field)context.getField().getRawMember());
        context.getParameterBuilder().description(this.descriptions.resolve(apiModelProperty.value())).required(apiModelProperty.required()).allowableValues(allowable).parameterAccess(apiModelProperty.access()).hidden(apiModelProperty.hidden()).build();
    }

3、这个地方可以看到 在构建parameter的时候并没有把apiModelProperty.name()替换成字段名。（swagger 这里不把name设为字段名。可以去GitHub上看到作者说明并没有打算把name映射到字段名上。而是name用作其他的用途）

好在swagger 支持重写ParameterBuilder 就可以根据自身的业务需求进行扩展。
重写SwaggerExpandedParameterBuilder 的apply方法步骤自定义MySwaggerExpandedParameterBuilder 类继承SwaggerExpandedParameterBuilder 类重写apply方法。整体实现如下

    public class MySwaggerExpandedParameterBuilder extends SwaggerExpandedParameterBuilder { 
   
    private final DescriptionResolver descriptions;

    @Autowired
    public CbcSwaggerExpandedParameterBuilder(DescriptionResolver descriptions) { 
   
        super(descriptions);
        this.descriptions = descriptions;
    }
    @Override
    public void apply(ParameterExpansionContext context) { 
   
        Optional<ApiModelProperty> apiModelPropertyOptional = ApiModelProperties.findApiModePropertyAnnotation((AnnotatedElement)context.getField().getRawMember());
        if (apiModelPropertyOptional.isPresent()) { 
   
            this.fromApiModelProperty(context, (ApiModelProperty)apiModelPropertyOptional.get());
        }
        super.apply(context);
    }
    private void fromApiModelProperty(ParameterExpansionContext context, ApiModelProperty apiModelProperty) { 
   
        String allowableProperty = Strings.emptyToNull(apiModelProperty.allowableValues());
        AllowableValues allowable = this.allowableValues(Optional.fromNullable(allowableProperty), (Field)context.getField().getRawMember());
        ParameterBuilder parameterBuilder = context.getParameterBuilder();
        if (!StringUtils.isEmpty(apiModelProperty.name())){ 
   
            parameterBuilder.name(apiModelProperty.name());
        }
        parameterBuilder.description(this.descriptions.resolve(apiModelProperty.value())).required(apiModelProperty.required()).allowableValues(allowable).parameterAccess(apiModelProperty.access()).hidden(apiModelProperty.hidden()).build();
    }

    private AllowableValues allowableValues(Optional<String> optionalAllowable, Field field) { 
   
        AllowableValues allowable = null;
        if (field.getType().isEnum()) { 
   
            allowable = new AllowableListValues(this.getEnumValues(field.getType()), "LIST");
        } else if (optionalAllowable.isPresent()) { 
   
            allowable = ApiModelProperties.allowableValueFromString((String)optionalAllowable.get());
        }

        return (AllowableValues)allowable;
    }

    private List<String> getEnumValues(Class<?> subject) { 
   
        return Lists.transform(Arrays.asList(subject.getEnumConstants()), new Function<Object, String>() { 
   
            public String apply(Object input) { 
   
                return input.toString();
            }
        });
    }
} 

4、 具体改动如下

   private void fromApiModelProperty(ParameterExpansionContext context, ApiModelProperty apiModelProperty) { 
   
        String allowableProperty = Strings.emptyToNull(apiModelProperty.allowableValues());
        AllowableValues allowable = this.allowableValues(Optional.fromNullable(allowableProperty), (Field)context.getField().getRawMember());
        ParameterBuilder parameterBuilder = context.getParameterBuilder();
        if (!StringUtils.isEmpty(apiModelProperty.name())){ 
   
            parameterBuilder.name(apiModelProperty.name());
        }

5、 获取apiModelProperty注解上的name判断进行非空校验。如果非空则替换field name