如何让Swagger UI请求Authorization Header而非UserEntity参数？

一、核心问题解决方案：无需重写端点/过滤器，通过Swagger注解+配置实现需求 #

你完全不需要修改现有端点和过滤器的核心逻辑，通过以下两步就能让Swagger UI不再展示UserEntity参数，转而显示Authorization Header输入框：

1. 标记UserEntity参数为Swagger忽略项 #

在端点的@AuthenticationPrincipal UserEntity user参数上添加@ApiIgnore注解，Swagger就不会将其识别为需要用户输入的请求参数：

@PostMapping("/operation/finiquito")
public ResponseEntity<?> calculateFiniquito(
        @ApiIgnore @AuthenticationPrincipal UserEntity user,
        @RequestBody FiniquitoRequest finiquito, 
        HttpServletRequest request) throws IOException {
    return service.calculateFiniquitoAndCreateHistory(user, finiquito, request);
}

2. 配置Swagger全局Authorization Header #

修改你的Docket Bean，添加全局的Header参数配置，让Swagger UI统一显示Token输入区域：

@Bean
public Docket api() {
    // 定义JWT授权Header参数
    Parameter authHeader = new ParameterBuilder()
            .name("Authorization")
            .description("JWT Token格式：Bearer {你的Token内容}")
            .modelRef(new ModelRef("string"))
            .parameterType("header")
            .required(true) // 根据业务需求设置是否必填
            .build();

    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.operaciones.microservicio.Controller"))
            .paths(PathSelectors.any())
            .build()
            .globalOperationParameters(Collections.singletonList(authHeader));
}

二、关于当前写法的合理性 #

你用@AuthenticationPrincipal直接获取认证后的UserEntity的写法不是不良实践，反而符合Spring Security的最佳规范：

• 代码简洁直观，无需手动从SecurityContextHolder中提取用户信息
• 明确表达了接口对认证用户的依赖，可读性强

三、代码优化建议 #

1. 过滤器异常处理优化 #

当前过滤器捕获所有异常仅打印info日志，建议区分异常类型并返回对应HTTP响应，同时细化日志级别：

@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
        throws ServletException, IOException {
    try {
        String token = getJwtFromRequest(request);
        if (StringUtils.hasText(token) && tokenProvider.validateToken(token)) {
            Long userId = tokenProvider.getUserIdFromJWT(token);
            UserEntity user = (UserEntity) userDetailsService.loadUserById(userId);
            UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
                    user, null, user.getAuthorities()); // 注意：credentials设为null更安全，因为JWT认证无需存储凭证
            authentication.setDetails(new WebAuthenticationDetails(request));
            SecurityContextHolder.getContext().setAuthentication(authentication);
        }
    } catch (JwtException ex) {
        // 针对JWT相关异常（过期、签名无效等）返回401
        log.error("JWT认证失败，请求URI：{}，错误信息：{}", request.getRequestURI(), ex.getMessage());
        response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "无效或过期的授权Token");
        return; // 终止过滤器链，避免后续无意义处理
    } catch (Exception ex) {
        log.error("认证过程发生未知错误，请求URI：{}", request.getRequestURI(), ex);
        response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, "认证服务异常");
        return;
    }
    filterChain.doFilter(request, response);
}

2. 避免强制类型转换 #

(UserEntity) userDetailsService.loadUserById(userId)的强制转换不安全，建议：

• 让ServicioUsuarioUserDetails的loadUserById方法直接返回UserEntity（前提是UserEntity实现了UserDetails接口）
• 或者新增一个专门查询UserEntity的方法，比如findUserById(Long userId)，替代强制转换

3. 简化HttpServletRequest参数传递 #

如果你的calculateFiniquitoAndCreateHistory方法仅用request获取客户端IP、请求URI等信息，可以从UserEntity关联的Authentication对象中提取，无需直接传递HttpServletRequest：

// 从Authentication中获取请求详情
WebAuthenticationDetails details = (WebAuthenticationDetails) SecurityContextHolder.getContext().getAuthentication().getDetails();
String clientIp = details.getRemoteAddress();

4. 明确接口返回类型 #

将ResponseEntity<?>改为具体的响应类型（比如ResponseEntity<FiniquitoCalculationResponse>），让Swagger能自动生成更清晰的响应文档，同时提升代码可读性。

内容的提问来源于stack exchange，提问作者Manuel Pablo Ramos Aguilar