Knife4j中如何自定义用户名密码验证逻辑？

Question

在使用Knife4j时，如何自定义用户名和密码的验证逻辑是一个常见的技术问题。默认情况下，Knife4j使用的是Swagger自带的授权机制，但实际项目中往往需要对接自定义的认证服务或数据库。例如，当我们在接口文档中使用Basic Auth时，如何让Knife4j根据我们定义的规则（如从数据库查询用户信息）来校验用户名和密码？这需要通过扩展Spring Security或直接修改Knife4j的全局配置来实现。具体来说，可以通过实现`AuthenticationProvider`接口并将其集成到Spring Security配置中，或者利用Knife4j提供的`OpenApiResource`扩展点来自定义验证逻辑。这种自定义方式不仅提升了文档的安全性，还能够更好地与项目的认证体系保持一致。

Answer 1

1. 问题概述

在使用Knife4j生成接口文档时，如何自定义用户名和密码的验证逻辑是一个常见的技术问题。默认情况下，Knife4j继承了Swagger的授权机制，通常只支持简单的Basic Auth模式。然而，在实际项目中，我们往往需要对接自定义认证服务或数据库，以实现更复杂、更安全的用户校验逻辑。

例如，当我们在接口文档中使用Basic Auth时，如何让Knife4j根据我们定义的规则（如从数据库查询用户信息）来校验用户名和密码？这需要通过扩展Spring Security或直接修改Knife4j的全局配置来实现。

2. 技术分析

为了解决上述问题，我们需要从以下几个方面进行分析：

• 默认授权机制：Knife4j默认使用Swagger的授权机制，无法满足复杂的认证需求。
• 扩展点选择：可以通过Spring Security的AuthenticationProvider接口或Knife4j提供的OpenApiResource扩展点来自定义验证逻辑。
• 安全性提升：自定义验证逻辑可以更好地与项目的认证体系保持一致，从而提升文档的安全性。

以下是两种主要的技术实现路径：

2.1 基于Spring Security的解决方案

通过实现AuthenticationProvider接口，并将其集成到Spring Security配置中，可以完成自定义的用户名和密码校验逻辑。

@Component
public class CustomAuthenticationProvider implements AuthenticationProvider {
    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
        String username = authentication.getName();
        String password = authentication.getCredentials().toString();

        // 自定义校验逻辑，例如从数据库查询用户信息
        if (isValidUser(username, password)) {
            return new UsernamePasswordAuthenticationToken(username, password, new ArrayList<>());
        } else {
            throw new BadCredentialsException("Invalid username or password");
        }
    }

    private boolean isValidUser(String username, String password) {
        // 模拟数据库查询逻辑
        return "admin".equals(username) && "password123".equals(password);
    }

    @Override
    public boolean supports(Class authentication) {
        return authentication.equals(UsernamePasswordAuthenticationToken.class);
    }
}
    

2.2 基于Knife4j的扩展点解决方案

利用Knife4j提供的OpenApiResource扩展点，可以直接修改其全局配置，实现自定义验证逻辑。

@Configuration
public class Knife4jConfig {
    @Bean
    public OpenApiResource openApiResource() {
        OpenApiResource resource = new OpenApiResource();
        resource.setAuthenticator(new CustomAuthenticator());
        return resource;
    }

    static class CustomAuthenticator implements Authenticator {
        @Override
        public boolean authenticate(HttpServletRequest request, HttpServletResponse response) {
            String authHeader = request.getHeader("Authorization");
            if (authHeader != null && authHeader.startsWith("Basic ")) {
                String base64Credentials = authHeader.substring("Basic ".length()).trim();
                String credentials = new String(Base64.getDecoder().decode(base64Credentials));
                String[] values = credentials.split(":");
                String username = values[0];
                String password = values[1];

                // 自定义校验逻辑
                return "admin".equals(username) && "password123".equals(password);
            }
            return false;
        }
    }
}
    

3. 实现步骤总结

以下是基于Spring Security和Knife4j扩展点的实现步骤对比表：

实现方式	优点	缺点
Spring Security	与项目认证体系无缝集成	需要额外配置Spring Security
Knife4j扩展点	无需依赖Spring Security	灵活性较低，仅适用于简单场景

4. 流程图说明

以下流程图展示了基于Spring Security的自定义验证逻辑实现过程：

sequenceDiagram
        participant User
        participant Knife4j
        participant SpringSecurity
        participant Database

        User->>Knife4j: 请求接口文档
        Knife4j->>SpringSecurity: 调用AuthenticationProvider
        SpringSecurity->>Database: 查询用户信息
        Database-->>SpringSecurity: 返回查询结果
        SpringSecurity-->>Knife4j: 返回验证结果
        Knife4j-->>User: 返回接口文档