1. @ApiParam的hidden属性不生效
项目采用Swagger生成在线文档，由于SpringMVC有一些内置对象可以直接注入到处理器方法参数上，所以为了方便，在处理器方法上注入了Principal参数，获取当前登录对象，相关的代码如下。
@PostMapping("/setProjectManager")
@ApiOperation(value = "设置项目经理", notes = "设置项目经理 0-否 1-是")
public ControllerResult<String> setProjectManager(@Valid @RequestBody SetProjectManagerReq req, BindingResult bindingResult,
@ApiParam(name = "principal",value = "登录用户",hidden = true) Principal principal) {
// 省略...
}
由于Principal是SpringMVC自动注入的参数，不需要前端传递，但实际上打开该接口的在线文档，发现Principal参数虽然通过@ApiParam的hidden属性，设置了隐藏，仍然体现在接口参数中。
接口请求参数列表1
接口请求参数列表2
为了不误导前端传参，想要将多出来的参数name隐藏起来，通过追踪Swagger源码，在OperationParameterReader类中发现如下逻辑。
private List<Compatibility<springfox.documentation.service.Parameter, RequestParameter>> readParameters(OperationContext context) {
// 解析处理器上的所有参数
List<ResolvedMethodParameter> methodParameters = context.getParameters();
List<Compatibility<springfox.documentation.service.Parameter, RequestParameter>> parameters = new ArrayList<>();
LOGGER.debug("Reading parameters for method {} at path {}", context.getName(), context.requestMappingPattern());
int index = 0;
for (ResolvedMethodParameter methodParameter : methodParameters) {
LOGGER.debug("Processing parameter {}", methodParameter.defaultName().orElse("<unknown>"));
ResolvedType alternate = context.alternateFor(methodParameter.getParameterType());
// 是否跳过当前参数的显示
if (!shouldIgnore(methodParameter, alternate, context.getIgnorableParameterTypes())) {
ParameterContext parameterContext = new ParameterContext(methodParameter,
context.getDocumentationContext(),
context.getGenericsNamingStrategy(),
context,
index++);
// 是否应该将该参数展开展示
if (shouldExpand(methodParameter, alternate)) {
parameters.addAll(
expander.expand(
new ExpansionContext("", alternate, context)));
} else {
parameters.add(pluginsManager.parameter(parameterContext));
}
}
}
return parameters.stream()
.filter(hiddenParameter().negate()) // 根据注解的hidden属性过滤改参数是否显示
.collect(toList());
}
在上述源码中，可以看到关键的两个方法shouldIgnore,shouldExpand，这两个方法源码如下。
private boolean shouldIgnore(final ResolvedMethodParameter parameter, ResolvedType resolvedParameterType, final Set<Class> ignorableParamTypes) {
if (ignorableParamTypes.contains(resolvedParameterType.getErasedType())) {
return true;
}
return ignorableParamTypes.stream()
.filter(Annotation.class::isAssignableFrom)
.anyMatch(parameter::hasParameterAnnotation);
}
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)
&& !builtInScalarType(resolvedParamType.getErasedType()).isPresent()
&& !enumTypeDeterminer.isEnum(resolvedParamType.getErasedType())
&& !isContainerType(resolvedParamType)
&& !isMapType(resolvedParamType);
}
通过上述源码，可以了解到Swagger在解析方法参数时，会在shouldIgnore根据一定规则过滤参数，通过过滤之后的参数，Swagger又会通过shouldExpand判断当前参数是否需要展开，再进一步追溯Swagger对参数的过滤条件，可以在Defaults类中看到注册的过滤条件。
private void initIgnorableTypes() {
ignored = new HashSet<>();
ignored.add(Class.class);
ignored.add(Void.class);
ignored.add(Void.TYPE);
ignored.add(HttpHeaders.class);
ignored.add(BindingResult.class);
ignored.add(UriComponentsBuilder.class);
ignored.add(ApiIgnore.class); //用于忽略参数
classFor("javax.servlet.ServletRequest").ifPresent(it -> ignored.add(it));
classFor("javax.servlet.ServletResponse").ifPresent(it -> ignored.add(it));
classFor("javax.servlet.http.HttpServletRequest").ifPresent(it -> ignored.add(it));
classFor("javax.servlet.http.HttpServletResponse").ifPresent(it -> ignored.add(it));
classFor("javax.servlet.ServletContext").ifPresent(it -> ignored.add(it));
}
综合上述源码逻辑，由于Principal参数不符合过滤条件，同时满足展开条件，那么Swagger就会解析接口中的getXXX函数，从而作为方法的参数进行展示，而被展开的类属性考虑应该是使用@ApiModelProperty注解的hidden属性隐藏（未验证）。
因此回到本坑最初的问题，@ApiParam注解的hidden属性并非没有用，而是他只能作用于非复合类的处理器参数上，如果要让一个处理器的复合参数不显示，应该为其添加@ApiIgnore注解。
