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注解。