Spring Boot 3 整合Knife4j（OpenAPI3规范）

原创

Harry技术

发布于 2025-01-13 09:37:58

1800

Spring Boot 3 整合Knife4j（OpenAPI3规范）

推荐框架 基于SpringBoot3+Vue3前后端分离的Java快速开发框架项目简介：基于 JDK 17、Spring Boot 3、Spring Security 6、JWT、Redis、Mybatis-Plus、Knife4j等构建后端，基于Vue 3、Element-Plus 、TypeScript等构建前端的分离单体权限管理系统。 项目地址： 后端： gitee: https://gitee.com/harry-tech/harry.git gitcode: https://gitcode.com/harry-tech/harry.git
前端： gitee: https://gitee.com/harry-tech/harry-vue.git https://gitcode.com/harry-tech/harry-vue.git 觉着有帮助，给个Star再走呗公众号搜“Harry技术”,关注我,带你看不一样的人间烟火！

Knife4j官网：

地址：https://doc.xiaominfo.com/ Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案。

提示
Spring Boot 3 只支持OpenAPI3规范 Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突 JDK版本必须 >= 17

更新原由

由于springfox长久未更新，并且Swagger2规范在目前来看，一定程度上也并未升级，规范已经全部往OpenAPI3规范靠拢，自4.0版本开始，Knife4j提供对OpenAPI3规范的适配，底层规范解析框架依赖springdoc-openapi项目。因此，在Spring Boot 3.x版本中，开发者应该选择OpenAPI3规范来作为应用框架的开发首选方案。

Knife4j自4.0版本为Spring Boot 3框架提供了适配

引用组件maven坐标如下：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>{maven仓库最新版本}</version>
</dependency>

规范说明

针对Swagger2规范和OpenAPI3规范的说明：

服务端规范解析说明
在Spring Boot框架中,Knife4j对于服务端将Spring的开放接口解析成Swagger2或者OpenAPI3规范的框架，也是依赖的第三方框架组件。说明如下：
Swagger2规范：依赖Springfox项目，该项目目前几乎处于停更状态，但很多老项目依然使用的是该规范，所以Knife4j在更新前端Ui的> 同时也继续保持了兼容 OpenAPI3规范：依赖Springdoc项目，更新发版频率非常快，建议开发者尽快迁移过来使用OpenAPI3规范,Knife4j后面的重心也会在这里。

创建项目

引入依赖

    <properties>
        <java.version>17</java.version>

        <knife4j.version>4.5.0</knife4j.version>
    </properties>   

	<!--Knife4j https://doc.xiaominfo.com/-->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
        <version>${knife4j.version}</version>
    </dependency>

创建demo

实体类 SysUser

/**
 * @author harry
 * @公众号 Harry技术
 */
@Data
public class SysUser implements Serializable {
    @Serial
    private static final long serialVersionUID = 1L;
    /**
     * ID
     */
    @Schema(description = "ID")
    private Long id;

    /**
     * 用户名
     */
    @Schema(description = "用户名")
    private String username;

    /**
     * 密码
     */
    @Schema(description = "密码")
    private String password;

    /**
     * 性别 0 男 1 女 2 未知
     */
    @Schema(description = "性别 0 男 1 女 2 未知")
    private String sex;

    /**
     * 昵称
     */
    @Schema(description = "昵称")
    private String nickName;

    /**
     * 账号状态 0 禁用 1 启用
     */
    @Schema(description = "账号状态 0 禁用 1 启用")
    private String status;

    /**
     * 有效状态 0 无效 1 有效
     */
    @Schema(description = "有效状态 0 无效 1 有效")
    private Integer valid;


}

接口 UserController

/**
 * @author harry
 * @公众号 Harry技术
 */
@Slf4j
@Tag(name = "用户管理")
@RestController
public class UserController {

    @Operation(summary = "获取单个用户")
    @PostMapping("/user/info")
    public SysUser getUserInfo() {
        SysUser sysUser = new SysUser();
        sysUser.setId(1L);
        sysUser.setUsername("harry");
        sysUser.setSex("1");
        sysUser.setNickName("harry");
        return sysUser;
    }

    @Operation(summary = "获取所有用户")
    @PostMapping("/user/list")
    public List<SysUser> list() {
        List<SysUser> list = new ArrayList<>();
        for (int i = 0; i < 10; i++) {
            SysUser sysUser = new SysUser();
            sysUser.setId(i + 1L);
            sysUser.setUsername("harry" + i);
            sysUser.setSex("1");
            sysUser.setNickName("harry" + i);
            list.add(sysUser);
        }
        return list;
    }

}

配置yml

开发者即可完全参考springdoc-openapi的项目说明，Knife4j只提供了增强部分，如果要启用Knife4j的增强功能，可以在配置文件中进行开启

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

配置 SwaggerConfig

/**
 * @author harry
 * @公众号 Harry技术
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public GlobalOpenApiCustomizer orderGlobalOpenApiCustomizer() {
        return openApi -> {
            // 可以自定义一些配置，如：
            // 配置全局鉴权参数-Authorize
            // 根据@Tag 上的排序，写入x-order
        };
    }

    @Bean
    public OpenAPI openApi() {

        return new OpenAPI().info(new io.swagger.v3.oas.models.info.Info()
                .description("Harry技术")
                .version("v1.0.0")
                .title("Spring Boot 3整合Knife4j（OpenAPI3规范）"));
    }

}

如果在你的项目中引入了Spring Security、 Shrio等安全框架，需要对/v3/api-docs/**、/doc.html、/swagger-resources/**、/webjars/**、/swagger-ui/**、/swagger-ui.html加入白名单。