Springboot 3整合Knife4j（Swagger3、OpenApi3）

文章目录

前言

springboot 3开始javax包改成了jakarta，而swagger-oas等包中依然使用的是javax，所以报错。另外springfox已经停止更新有段时间了，并且不支持OpenAPI 3标准，升级Springboot 3.0以后会有更多问题暴露出来。而SpringBoot 3只支持OpenAPI 3规范，因此Spring官网推荐了Springdoc

OpenApi 3的规范，目前针对Java的Spring Boot项目，主要支持的有2个版本：

• springfox 3.0.0： 同时兼容OpenAPI 2以及OpenAPI 3，但是停更很久了
• springdoc-openapi：兼容OpenAPI 3规范，更新速度频繁
• Knife4j：在只有的OpenAPI 3规范中，底层基础框架选择springdoc-openapi项目，针对Springfox 3.0.0版本会放弃

一、Spring Boot 3.0整合Knife4j

以下是一些常见的Spring Boot版本及其对应的Knife4j版本兼容推荐：
Spring Boot版本Knife4j Swagger 2规范Knife4j OpenAPI 3规范1.5.x ~ 2.0.0< Knife4j 2.0.0>= Knife4j 4.0.02.0 ~ 2.2Knife4j 2.0.0 ~ 2.0.6>= Knife4j 4.0.02.2.x ~ 2.4.0Knife4j 2.0.6 ~ 2.0.9>= Knife4j 4.0.02.4.0 ~ 2.7.x>= Knife4j 4.0.0>= Knife4j 4.0.0>= 3.0>= Knife4j 4.0.0>= Knife4j 4.0.0

参考文档：关于Knife4j适配不同Spring Boot版本的说明文档

项目配置：

JDK：22

SpringBoot：3.3.1

Knife4j：4.5.0

温馨提示：

二、OpenApi 3注解的使用规范

• Swagger 3(OpenApi 3) 注解与Swagger 2注解的对比
  Swagger 2OpenAPI 3注解位置作用@Api**@Tag(name = “接口类名”,description = “接口类描述”)Controller类描述此controller的信息@ApiOperation(value = “接口方法描述”)@Operation(summary =“接口方法描述”)Api端口方法描述此Api的信息@ApiImplicitParams@ParametersApi端口方法描述参数信息@ApiImplicitParam@Parameter(description=“参数描述”)Api方法的参数描述参数信息@ApiParam@Parameter(description=“参数描述”)Api方法的参数-@ApiIgnore@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden**-用在各种地方，用于隐藏其Api@ApiModel**@SchemaDTO类用于Entity，以及Entity的属性上@ApiModelProperty@Schema**DTO属性用于Entity，以及Entity的属性上
  参考链接: 从 Springfox Swagger 2 迁移到 Springdoc Open API

三、使用步骤

1.Spring Boot 3.0中使用knife4j

• 在pom.xml文件中导入knife4j的依赖（本文springboot的版本是3.3.1）

<!-- Swagger3-knife4j依赖 --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.5.0</version></dependency>

其实现在就可以使用Knife4j了，暂不做其他配置，启动项目，浏览器输入http://localhost:8080/doc.html查看接口文档

• 由于我们没有进行任何的属性配置，所以看到的页面是knife4j的初始页面

2.在application.yml中添加knife4j相关配置

# springdoc-openapi项目配置springdoc:swagger-ui:#自定义swagger前端请求路径,输入http:localhost:8080/swagger-ui.html会自动重定向到swagger页面path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:path: /v3/api-docs    #swagger后端请求地址enabled:true#是否开启文档功能group-configs:-group:'default'#分组名称paths-to-match:'/**'#配置需要匹配的路径,默认为/**packages-to-scan: com.blog.patrick    #配置要扫描包的路径,一般配置到启动类所在的包名# knife4j的增强配置，不需要增强可以不配(建议配置一下)knife4j:enable:true#开启knife4j,无需添加@EnableKnife4j注解setting:language: zh_cn   #中文swagger-model-name: 实体类列表   #重命名SwaggerModel名称,默认#开启Swagger的Basic认证功能,默认是falsebasic:enable:true# Basic认证用户名username:******# Basic认证密码password:******

3.创建config包，在其中新建一个配置类

• 定义配置类WebMvcConfig，实现静态资源映射，将knife4j相关资源放行，保证生成的接口文档能够正常进行展示

packagecom.blog.patrick.config;importorg.springframework.context.annotation.Configuration;importorg.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;importorg.springframework.web.servlet.config.annotation.WebMvcConfigurer;/**
 * <p>
 * 配置类,注册web层相关组件
 * </p>
 *
 * @author Patrick
 * @since 2024-07-02
 */@ConfigurationpublicclassWebMvcConfigimplementsWebMvcConfigurer{/**
     * 设置静态资源映射
     * @param registry 
     */@OverridepublicvoidaddResourceHandlers(ResourceHandlerRegistry registry){// 添加静态资源映射规则
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");//配置 knife4j 的静态资源请求映射地址
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}

4.在config包下新建Knife4jConfig.java文件

• 该文件主要进行Knife4j的属性配置，如：作者、版本、接口分组等

packagecom.blog.patrick.config;importio.swagger.v3.oas.models.OpenAPI;importio.swagger.v3.oas.models.info.Contact;importio.swagger.v3.oas.models.info.Info;importio.swagger.v3.oas.models.info.License;importorg.springdoc.core.models.GroupedOpenApi;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;/**
 * <p>
 * Knife4j整合Swagger3 Api接口文档
 * </p>
 *
 * @author Patrick
 * @since 2024-07-02
 */@ConfigurationpublicclassKnife4jConfig{@BeanpublicGroupedOpenApiadminApi(){// 创建了一个api接口的分组returnGroupedOpenApi.builder().group("admin-api")// 分组名称.pathsToMatch("/**")// 接口请求路径规则.build();}@BeanpublicOpenAPIopenAPI(){returnnewOpenAPI().info(newInfo()// 基本信息配置.title("Knife4j整合Swagger3 Api接口文档")// 标题.description("Knife4j后端接口服务...")// 描述Api接口文档的基本信息.version("v1.0.0")// 版本// 设置OpenAPI文档的联系信息，包括联系人姓名为"patrick"，邮箱为"[email protected]"。.contact(newContact().name("patrick").email("[email protected]"))// 设置OpenAPI文档的许可证信息，包括许可证名称为"Apache 2.0"，许可证URL为"http://springdoc.org"。.license(newLicense().name("Apache 2.0").url("http://springdoc.org")));}}

5.entity实体类

@Schema(description = “ ”)： 标记实体类属性

@Data@TableName("t_user")@Schema(description ="用户实体")publicclassUserimplementsSerializable{@Schema(description ="用户id")privateInteger id;@Schema(description ="用户昵称")privateString nickname;@Schema(description ="用户名")privateString username;@Schema(description ="用户密码")privateString password;}

6.controller控制层

@Tag(name = “ ”)： 标记接口类别
@Operation(summary =“ ”)： 标记接口操作

• 创建(create) – 使用Post方法;
• 修改(update) – 使用Post方法;
• 删除(delete) – 使用Delete方法;

@RestController@Tag(name ="用户列表")@RequestMapping("/user")publicclassUserController{@AutowiredUserService userService;/**
     * 用户列表
     * @return
     */@Operation(summary ="用户列表")@GetMapping("/list")publicJsonResultlist(){List<User> userList = userService.findAll();returnJsonResult.success().data("userList", userList);}}

四、重启项目并访问接口文档

• 访问http://localhost:8080/doc.html，可以看到我们配置的属性已经在页面中显示出来了

五、Springboot启动类优化

• 每次都需要打开浏览器输入地址访问，对开发者很不友好，因此采取以下优化

@Slf4j@SpringBootApplicationpublicclassBlogApplication{publicstaticvoidmain(String[] args){ConfigurableEnvironment env =SpringApplication.run(BlogApplication.class, args).getEnvironment();

        log.info("\n----------------------------------------------------------\n\t"+"Application: '{}' is running Success! \n\t"+"Local URL: \thttp://localhost:{}\n\t"+"Document:\thttp://localhost:{}/doc.html\n"+"----------------------------------------------------------",
                env.getProperty("spring.application.name"),
                env.getProperty("server.port"),
                env.getProperty("server.port"));}}

• 项目启动，控制台打印日志如下：