SpringBoot集成Knife4j接口管理工具

news2025/4/5 22:21:33

SpringBoot集成Knife4j接口管理工具

- 1、导入依赖包
- 2、配置Knife4j
- 3、放行Knife4j的请求
- 4、使用Knife4j注解
- 5、实现效果

平时开发项目都用的是Swagger2或者Swagger3，但是这两个UI看起来不是很舒服，今天看到了Knife4j，它对Swagger进行了增强，有很多个性化需求。Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案。

官网地址：https://doc.xiaominfo.com/

1、导入依赖包

在maven项目的pom.xml中引入Knife4j的依赖包

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
        </dependency>

可以在Dependencies中查看是否引入成功。

2、配置Knife4j

在SpringBoot中创建swagger的配置类，如下

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("token")
                .description("用户token")
                .defaultValue("")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(tokenPar.build());
        //添加head参数end

        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        //.title("swagger-bootstrap-ui-demo RESTful APIs")
                        .description("# swagger-bootstrap-ui-demo RESTful APIs")
                        .termsOfServiceUrl("www.codeleader.top")
                        .contact("test@qq.com")
                        .version("1.0")
                        .build())
                .globalOperationParameters(pars)
                //分组名称
                .groupName("2.X版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.java1234"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

官网的配置如下图所示，我多配置了个head参数，目的是为了每次请求的时候在请求头上带上token参数，方便后端JWT的校验。

3、放行Knife4j的请求

由于我项目集成了SpringSecurity，所以这些请求默认都会被拦截，所以这里在配置类中放行这些文档的请求就行。

在SpringSecurity配置类中重写WebSecurityConfigurerAdapter类的configure(WebSecurity web)方法，在这里放行指定的请求即可。

/**
     * 配置哪些请求不拦截，放行swagger
     */
    @Override
    public void configure(WebSecurity web) throws Exception {
       web.ignoring().mvcMatchers("/favicon.ico","/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**", "/doc.html");
    }

4、使用Knife4j注解

@Api(tags = "用户管理")
@RestController
@RequestMapping("/sys/user")
public class SysUserController {

    @Autowired
    private SysUserService sysUserService;

    @Autowired
    private SysRoleService sysRoleService;

    @Autowired
    private SysUserRoleService sysUserRoleService;

    @Autowired
    private BCryptPasswordEncoder bCryptPasswordEncoder;

    @Value("${avatarImagesFilePath}")
    private String avatarImagesFilePath;

    @ApiOperation("更新个人信息")
    @PostMapping("/save")
    @PreAuthorize("hasAnyAuthority('system:user:edit','system:user:add')")
    public R save(@RequestBody @Valid SysUser sysUser){
        if(sysUser.getId()==null||sysUser.getId()==-1){
            sysUser.setPassword(bCryptPasswordEncoder.encode(sysUser.getPassword()));
            sysUserService.save(sysUser);
        }else{
            sysUserService.updateById(sysUser);
        }
        return R.ok();
    }

    @ApiOperation("修改密码")
    @PostMapping("updateUserPwd")
    @PreAuthorize("hasAuthority('system:user:edit')")
    public R updateUserPwd(@RequestBody SysUser sysUser){
        SysUser currentUser = sysUserService.getById(sysUser.getId());
        if(bCryptPasswordEncoder.matches(sysUser.getOldPassword(),currentUser.getPassword())){
            currentUser.setPassword(bCryptPasswordEncoder.encode(sysUser.getNewPassword()));
            sysUserService.updateById(currentUser);
            return R.ok();
        }else{
            return R.error("输入旧密码错误!");
        }

    }
}

@Api(tags = "用户管理")定义标签分组接口，在这个类下定义的所有接口将位于这个标签之下

@ApiOperation()定义具体的接口标题信息，notes可以为这个标签添加注释

常用注解如下：

注解	作用
@Api	修饰整个类，描述Controller的作用
@ApiOperation	描述一个类的一个方法，或者说一个接口
@ApiParam	单个参数描述
@ApiModel	用对象来接收参数
@ApiProperty	用对象接收参数时，描述对象的一个字段
@ApiResponse	HTTP响应其中1个描述
@ApiResponses	HTTP响应整体描述
@ApiIgnore	使用该注解忽略这个API
@ApiError	发生错误返回的信息
@ApiImplicitParam	一个请求参数
@ApiImplicitParams	多个请求参数