swagger2自定义隐藏实体类属性，swagger2版本2.8.0
博主将这个功能做了个组件，不想在项目中修改源码的请移步另一篇博客
假如接收参数的实体类中关联了其他对象，那么swagger2的页面中参数应该会多出来这些，dept.id，dept.deptName，或者集合属性，roles[0].id，roles[0].roleName等等。
这些属性有可能是不需要用来接收参数的，出现在文档中会给前端开发人员带来困惑
笔者在swagger2提供的配置中没有找到隐藏此类参数的设置
但是通过阅读源码找到了展开参数的类springfox.documentation.spring.web.readers.parameter.ModelAttributeParameterExpander，笔者通过继承这个类，并添加@Primary注解覆盖了源码中的逻辑，修改了getBeanPropertyNames方法，其他不变
package com.example.swagger;
import com.example.annotation.IgnoreSwaggerParameter;
import com.example.util.FieldUtil;
import com.fasterxml.classmate.ResolvedType;
import com.fasterxml.classmate.members.ResolvedField;
import com.google.common.annotations.VisibleForTesting;
import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import com.google.common.collect.FluentIterable;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;
import org.springframework.util.ClassUtils;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.schema.Maps;
import springfox.documentation.schema.Types;
import springfox.documentation.schema.property.field.FieldProvider;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.schema.AlternateTypeProvider;
import springfox.documentation.spi.schema.EnumTypeDeterminer;
import springfox.documentation.spi.service.contexts.DocumentationContext;
import springfox.documentation.spi.service.contexts.ParameterExpansionContext;
import springfox.documentation.spring.web.readers.parameter.ExpansionContext;
import springfox.documentation.spring.web.readers.parameter.ModelAttributeField;
import springfox.documentation.spring.web.readers.parameter.ModelAttributeParameterExpander;
import java.beans.BeanInfo;
import java.beans.IntrospectionException;
import java.beans.Introspector;
import java.beans.PropertyDescriptor;
import java.lang.reflect.Field;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import static com.google.common.base.Objects.equal;
import static com.google.common.base.Predicates.*;
import static com.google.common.base.Strings.isNullOrEmpty;
import static com.google.common.collect.FluentIterable.from;
import static com.google.common.collect.Lists.newArrayList;
import static com.google.common.collect.Sets.newHashSet;
import static springfox.documentation.schema.Collections.collectionElementType;
import static springfox.documentation.schema.Collections.isContainerType;
import static springfox.documentation.schema.Types.typeNameFor;
/**
* 覆盖{@link ModelAttributeParameterExpander}
* @see CustomizeModelAttributeParameterExpander#getBeanPropertyNames(Class)
* @see ModelAttributeParameterExpander#getBeanPropertyNames(Class)
* @see IgnoreSwaggerParameter
*/
@Component
@Primary
public class CustomizeModelAttributeParameterExpander extends ModelAttributeParameterExpander {
private static final Logger LOG = LoggerFactory.getLogger(CustomizeModelAttributeParameterExpander.class);
private final FieldProvider fieldProvider;
private final EnumTypeDeterminer enumTypeDeterminer;
@Autowired
public CustomizeModelAttributeParameterExpander(FieldProvider fields, EnumTypeDeterminer enumTypeDeterminer) {
super(fields, enumTypeDeterminer);
this.fieldProvider = fields;
this.enumTypeDeterminer = enumTypeDeterminer;
}
@Override
public List expand(ExpansionContext context) {
List parameters = newArrayList();
Set beanPropNames = getBeanPropertyNames(context.getParamType().getErasedType());
Iterable fields = FluentIterable.from(fieldProvider.in(context.getParamType()))
.filter(onlyBeanProperties(beanPropNames));
LOG.debug("Expanding parameter type: {}", context.getParamType());
AlternateTypeProvider alternateTypeProvider = context.getDocumentationContext().getAlternateTypeProvider();
FluentIterable modelAttributes = from(fields)
.transform(toModelAttributeField(alternateTypeProvider));
FluentIterable expendables = modelAttributes
.filter(not(simpleType()))
.filter(not(recursiveType(context)));
for (ModelAttributeField each : expendables) {
LOG.debug("Attempting to expand expandable field: {}", each.getField());
parameters.addAll(
expand(
context.childContext(
nestedParentName(context.getParentName(), each.getField()),
each.getFieldType(),
context.getDocumentationContext())));
}
FluentIterable collectionTypes = modelAttributes
.filter(and(isCollection(), not(recursiveCollectionItemType(context.getParamType()))));
for (ModelAttributeField each : collectionTypes) {
LOG.debug("Attempting to expand collection/array field: {}", each.getField());
ResolvedType itemType = collectionElementType(each.getFieldType());
if (Types.isBaseType(itemType) || enumTypeDeterminer.isEnum(itemType.getErasedType())) {
parameters.add(simpleFields(context.getParentName(), context.getDocumentationContext(), each));
} else {
parameters.addAll(
expand(
context.childContext(
nestedParentName(context.getParentName(), each.getField()),
itemType,
context.getDocumentationContext())));
}
}
FluentIterable simpleFields = modelAttributes.filter(simpleType());
for (ModelAttributeField each : simpleFields) {
parameters.add(simpleFields(context.getParentName(), context.getDocumentationContext(), each));
}
return FluentIterable.from(parameters).filter(not(hiddenParameters())).toList();
}
private Predicate recursiveCollectionItemType(final ResolvedType paramType) {
return new Predicate() {
@Override
public boolean apply(ModelAttributeField input) {
return equal(collectionElementType(input.getFieldType()), paramType);
}
};
}
private Predicate hiddenParameters() {
return new Predicate() {
@Override
public boolean apply(Parameter input) {
return input.isHidden();
}
};
}
private Parameter simpleFields(
String parentName,
DocumentationContext documentationContext,
ModelAttributeField each) {
LOG.debug("Attempting to expand field: {}", each);
String dataTypeName = Optional.fromNullable(typeNameFor(each.getFieldType().getErasedType()))
.or(each.getFieldType().getErasedType().getSimpleName());
LOG.debug("Building parameter for field: {}, with type: ", each, each.getFieldType());
ParameterExpansionContext parameterExpansionContext = new ParameterExpansionContext(
dataTypeName,
parentName,
each.getField(),
documentationContext.getDocumentationType(),
new ParameterBuilder());
return pluginsManager.expandParameter(parameterExpansionContext);
}
private Predicate recursiveType(final ExpansionContext context) {
return new Predicate() {
@Override
public boolean apply(ModelAttributeField input) {
return context.hasSeenType(input.getFieldType());
}
};
}
private Predicate simpleType() {
return and(not(isCollection()), not(isMap()),
or(
belongsToJavaPackage(),
isBaseType(),
isEnum()));
}
private Predicate isCollection() {
return new Predicate() {
@Override
public boolean apply(ModelAttributeField input) {
return isContainerType(input.getFieldType());
}
};
}
private Predicate isMap() {
return new Predicate() {
@Override
public boolean apply(ModelAttributeField input) {
return Maps.isMapType(input.getFieldType());
}
};
}
private Predicate isEnum() {
return new Predicate() {
@Override
public boolean apply(ModelAttributeField input) {
return enumTypeDeterminer.isEnum(input.getFieldType().getErasedType());
}
};
}
private Predicate belongsToJavaPackage() {
return new Predicate() {
@Override
public boolean apply(ModelAttributeField input) {
return ClassUtils.getPackageName(input.getFieldType().getErasedType()).startsWith("java.lang");
}
};
}
private Predicate isBaseType() {
return new Predicate() {
@Override
public boolean apply(ModelAttributeField input) {
return Types.isBaseType(input.getFieldType())
|| input.getField().getType().isPrimitive();
}
};
}
private Function toModelAttributeField(
final AlternateTypeProvider
alternateTypeProvider) {
return new Function() {
@Override
public ModelAttributeField apply(ResolvedField input) {
return new ModelAttributeField(fieldType(alternateTypeProvider, input), input);
}
};
}
private Predicate onlyBeanProperties(final Set beanPropNames) {
return new Predicate() {
@Override
public boolean apply(ResolvedField input) {
return beanPropNames.contains(input.getName());
}
};
}
private String nestedParentName(String parentName, ResolvedField field) {
String name = field.getName();
ResolvedType fieldType = field.getType();
if (isContainerType(fieldType) && !Types.isBaseType(collectionElementType(fieldType))) {
name += "[0]";
}
if (isNullOrEmpty(parentName)) {
return name;
}
return String.format("%s.%s", parentName, name);
}
private ResolvedType fieldType(AlternateTypeProvider alternateTypeProvider, ResolvedField field) {
return alternateTypeProvider.alternateFor(field.getType());
}
private Set getBeanPropertyNames(final Class clazz) {
try {
Set beanProps = new HashSet();
PropertyDescriptor[] propDescriptors = getBeanInfo(clazz).getPropertyDescriptors();
for (PropertyDescriptor propDescriptor : propDescriptors) {
// 增加逻辑，忽略@IgnoreSwaggerParameter注解的字段
Field field = FieldUtil.getDeclaredField(clazz, propDescriptor.getName());
if (field!=null) {
field.setAccessible(true);
IgnoreSwaggerParameter ignoreSwaggerParameter = field.getDeclaredAnnotation(IgnoreSwaggerParameter.class);
if (ignoreSwaggerParameter != null) {
continue;
}
}
// 增加结束
if (propDescriptor.getReadMethod() != null) {
beanProps.add(propDescriptor.getName());
}
}
return beanProps;
} catch (IntrospectionException e) {
LOG.warn(String.format("Failed to get bean properties on (%s)", clazz), e);
}
return newHashSet();
}
@VisibleForTesting
BeanInfo getBeanInfo(Class clazz) throws IntrospectionException {
return Introspector.getBeanInfo(clazz);
}
}
用到了自定义的IgnoreSwaggerParamer注解
package com.example.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
// swagger忽略的参数
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface IgnoreSwaggerParameter {
}
使用方式，在不需要递归展开的属性上加上IgnoreSwaggerParameter注解
package com.example.model.po;
import com.example.annotation.IgnoreSwaggerParameter;
import com.example.model.BaseModel;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.sql.Date;
import java.sql.Timestamp;
import java.util.List;
@Data
@ApiModel(value = "用户")
public class User extends BaseModel {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "用户id")
private Integer id;
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "密码")
private String password;
@ApiModelProperty(value = "邮箱")
private String email;
@ApiModelProperty(value = "昵称")
private String nickname;
@ApiModelProperty(value = "生日")
private Date birth;
@ApiModelProperty(value="登录时间")
private Timestamp logintime;
@ApiModelProperty(value = "部门id")
private Integer deptId;
@ApiModelProperty(value = "部门信息")
@IgnoreSwaggerParameter // 在不需要递归展开的属性上加上IgnoreSwaggerParameter注解
private Dept dept;
@ApiModelProperty(value = "角色信息")
@IgnoreSwaggerParameter
private List roles;
}
这样就可以自定义隐藏swagger2页面中的参数了。
如果有用的不对的地方，欢迎各位大佬批评指正。