如何解决@AuthenticationPrincipal引发的REST接口Swagger UI多余参数展示问题

Swagger（含Springfox、Springdoc两个主流实现）默认会无差别扫描Controller方法上的所有入参，它无法识别@AuthenticationPrincipal是Spring Security用于注入登录态对象的注解——这类参数完全不需要客户端传递，根本不属于API入参范畴。
因为CurrentUser继承了Spring Security的org.springframework.security.core.userdetails.User类，Swagger会顺着类的继承链，把父类所有公开属性（包括accountNonExpired、accountNonLocked、credentialsNonExpired、enabled、authorities、password等）全部当成接口需要客户端传递的参数，渲染到Swagger UI上。
你之前的尝试失效的原因有两个：

• 在CurrentUser类字段上加@ApiParam(hidden = true)的方式，只能隐藏当前类自己定义的字段，对父类继承来的属性完全没有作用；
• 在方法参数上加@ApiParam(hidden = true)的方式，属于Swagger对简单参数的配置逻辑，对被识别为复杂嵌套对象的参数不生效，配置会被Swagger默认的对象结构扫描逻辑覆盖。

方案1：单接口参数级快速隐藏（改动最小） #

根据你项目使用的Swagger版本，在对应方法的参数上增加专用的隐藏注解即可：

• 如果你使用的是Springfox（Swagger 2 版本）：直接加@ApiIgnore注解，从文档扫描层面直接剔除该参数，不会再触发后续的类结构解析

  @PutMapping("/change-email")
  public ResponseEntity<?> changeEmail(
      @AuthenticationPrincipal @ApiIgnore CurrentUser currentUser,
      @RequestBody @Valid ChangeEmailRequest changeEmailRequest, 
      BindingResult result
  ) {
      // 原有业务逻辑保持不变
  }
  

• 如果你使用的是Springdoc-openapi（Swagger 3 / OpenAPI 3 版本）：直接加@Parameter(hidden = true)注解

  @PutMapping("/change-email")
  public ResponseEntity<?> changeEmail(
      @AuthenticationPrincipal @Parameter(hidden = true) CurrentUser currentUser,
      @RequestBody @Valid ChangeEmailRequest changeEmailRequest, 
      BindingResult result
  ) {
      // 原有业务逻辑保持不变
  }
  

方案2：全局自动识别隐藏（一劳永逸，无需逐个方法加注解） #

如果项目里大量接口都使用了@AuthenticationPrincipal参数，不想每个方法重复加注解，可以通过扩展Swagger的解析插件，实现全局自动把所有带该注解的参数从文档中剔除：

• Springfox 环境下，注册自定义的OperationBuilderPlugin：

  @Component
  public class AuthenticationPrincipalIgnorePlugin implements OperationBuilderPlugin {
      @Override
      public void apply(OperationContext context) {
          context.getParameters().forEach(param -> {
              // 识别带@AuthenticationPrincipal的参数，主动从文档列表中移除
              if (param.hasAnnotation(AuthenticationPrincipal.class)) {
                  context.removeParameter(param);
              }
          });
      }
      @Override
      public boolean supports(DocumentationType delimiter) {
          return DocumentationType.SWAGGER_2.equals(delimiter);
      }
  }
  

• Springdoc-openapi 环境下，注册自定义的ParameterCustomizer：

  @Component
  public class AuthenticationPrincipalParamCustomizer implements ParameterCustomizer {
      @Override
      public Optional<Parameter> customize(Parameter parameter, MethodParameter methodParameter) {
          // 识别带@AuthenticationPrincipal的参数，直接标记为隐藏
          if (methodParameter.hasParameterAnnotation(AuthenticationPrincipal.class)) {
              parameter.hidden(true);
          }
          return Optional.of(parameter);
      }
  }
  

不要尝试在CurrentUser类上增加@Schema(hidden = true)或者@Api(hidden = true)注解，这类配置会把整个类完全隐藏，反而可能导致其他引用了该类的文档渲染出现异常。

内容的提问来源于stack exchange，提问作者Makary