Springboot 3整合Knife4j（Swagger3、OpenApi3）

最新推荐文章于 2025-07-04 09:00:00 发布
原创 最新推荐文章于 2025-07-04 09:00:00 发布 · 3.4k 阅读 · 33 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#spring boot #java #后端

文章目录

前言

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.0

2.0 ~ 2.2

Knife4j 2.0.0 ~ 2.0.6

>= Knife4j 4.0.0

2.2.x ~ 2.4.0

Knife4j 2.0.6 ~ 2.0.9

>= Knife4j 4.0.0

2.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 2

OpenAPI 3

注解位置

作用

@Api

@Tag(name = “接口类名”,description = “接口类描述”)

Controller类

描述此controller的信息

@ApiOperation(value = “接口方法描述”)

@Operation(summary =“接口方法描述”)

Api端口方法

描述此Api的信息

@ApiImplicitParams

@Parameters

Api端口方法

描述参数信息

@ApiImplicitParam

@Parameter(description=“参数描述”)

Api方法的参数

描述参数信息

@ApiParam

@Parameter(description=“参数描述”)

Api方法的参数

-

@ApiIgnore

@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden

-

用在各种地方，用于隐藏其Api

@ApiModel

@Schema

DTO类

用于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）

    com.github.xiaoymin knife4j-openapi3-jakarta-spring-boot-starter 4.5.0

其实现在就可以使用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认证功能,默认是false
  basic:
    enable: true
    # Basic认证用户名
    username: ******
    # Basic认证密码
    password: ******

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

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

    package com.blog.patrick.config;

    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

    /**

    • 配置类,注册web层相关组件

    • @author Patrick

    • @since 2024-07-02
      */
      @Configuration
      public class WebMvcConfig implements WebMvcConfigurer {

      /**

      • 设置静态资源映射
      • @param registry
        */
        @Override
        public void addResourceHandlers(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的属性配置，如：作者、版本、接口分组等

    package com.blog.patrick.config;

    import io.swagger.v3.oas.models.OpenAPI;
    import io.swagger.v3.oas.models.info.Contact;
    import io.swagger.v3.oas.models.info.Info;
    import io.swagger.v3.oas.models.info.License;
    import org.springdoc.core.models.GroupedOpenApi;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;

    /**

    • Knife4j整合Swagger3 Api接口文档

    • @author Patrick

    • @since 2024-07-02
      */
      @Configuration
      public class Knife4jConfig {

      @Bean
      public GroupedOpenApi adminApi() { // 创建了一个api接口的分组
      return GroupedOpenApi.builder()
      .group(“admin-api”) // 分组名称
      .pathsToMatch(“/**”) // 接口请求路径规则
      .build();
      }

      @Bean
      public OpenAPI openAPI(){
      return new OpenAPI()
      .info(new Info() // 基本信息配置
      .title(“Knife4j整合Swagger3 Api接口文档”) // 标题
      .description(“Knife4j后端接口服务…”) // 描述Api接口文档的基本信息
      .version(“v1.0.0”) // 版本
      // 设置OpenAPI文档的联系信息，包括联系人姓名为"patrick"，邮箱为"patrick@gmail.com"。
      .contact(new Contact().name(“patrick”).email(“patrick@gmail.com”))
      // 设置OpenAPI文档的许可证信息，包括许可证名称为"Apache 2.0"，许可证URL为"http://springdoc.org"。
      .license(new License().name(“Apache 2.0”).url(“http://springdoc.org”))
      );
      }
      }

5.entity实体类

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

@Data
@TableName("t_user")
@Schema(description = "用户实体")
public class User implements Serializable {

    @Schema(description = "用户id")
    private Integer id;
    
    @Schema(description = "用户昵称")
    private String nickname;
    
    @Schema(description = "用户名")
    private String username;

    @Schema(description = "用户密码")
    private String password;

}

6.controller控制层

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

  • 创建(create) – 使用Post方法;

  • 修改(update) – 使用Post方法;

  • 删除(delete) – 使用Delete方法;

    @RestController
    @Tag(name = “用户列表”)
    @RequestMapping(“/user”)
    public class UserController {

    @Autowired
UserService userService;

/**
 * 用户列表
 * @return
 */
@Operation(summary = "用户列表")
@GetMapping("/list")
public JsonResult list() {
    List<User> userList = userService.findAll();
    return JsonResult.success().data("userList", userList);
}

    }

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

在这里插入图片描述

五、Springboot启动类优化

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

    @Slf4j
    @SpringBootApplication
    public class BlogApplication {

    public static void main(String[] args) {
    ConfigurableEnvironment env = SpringApplication.run(BlogApplication.class, args).getEnvironment();

    log.info("

    " +
                    "Application: '{}' is running Success! 
" +
                    "Local URL: 	http://localhost:{}
" +
                    "Document:	http://localhost:{}/doc.html

    " +
    “----------------------------------------------------------”,
    env.getProperty(“spring.application.name”),
    env.getProperty(“server.port”),
    env.getProperty(“server.port”));
    }

    }

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

在这里插入图片描述

【SpringBoot】22、SpringBoot中整合knife4j接口文档
Asurplus
07-02 22万+
在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护 接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护中或者项目人员更迭，方便后期人员查看、维护 一、界面先赏 1、首页 2、接口文档 3、调试 二、整合 knife4j 1、引入 maven 依赖 <!-- knife4j接口文档 start --> <dependency> &lt
SpringBoot项目整合Knife4J
m0_74824483的博客
02-15 679
首先我们要明白我们为什么要去使用API文档，在前后端脱离开发的情况下，前端程序员无法实时的知道后端接口开发的进度，后端程序员总不能每_开发完一个接口或者更新一次接口_就去wx上去跟前端程序员说，嘿！哥们哥们，我新增了一个接口，这个接口是这样这样子…这样沟通的成本也太高了，而且有时候还说不明白，搞得双方都很难受，在这样的情况下，API文档应运而生。API 文档是开发者了解 API 功能和如何正确使用的主要来源。它提供了详细的指导，包括请求格式、参数说明、响应结构。
Knife4j-SpringBoot3-OpenAPI3：基本使用、生产环境关闭接口文档、配置文件、配置接口文档描述信息、OpenAPI3注解
宋冠巡的博客
10-08 3356
基本使用、生产环境关闭接口文档、配置文件、配置接口文档描述信息、OpenAPI3注解
Springboot3 集成knife4j(swagger)
清山博客
04-02 1505
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!2.Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突。版本集成knife4j叙述(请注意版本差别，不同版本写法不同)。1.Spring Boot 3 只支持OpenAPI3规范。3.JDK版本必须 >= 17。
Spring Boot 3 整合 Knife4j：从环境搭建到 API 文档生成实战​
最新发布
2501_92589102的博客
07-04 1322
Knife4j 是为 Java 开发者量身定制的 API 文档解决方案可视化文档界面：比原生 Swagger UI 更美观、操作更流畅增强功能：支持 API 分组、参数校验提示、在线测试轻量化：仅依赖 Swagger 核心库，无额外重量级依赖Spring Boot 原生支持：通过 Starter 一键整合自动化 API 文档生成与可视化在线接口测试与参数校验灵活的分组管理与安全配置Knife4j 在 Spring Boot 3 中的表现更加轻量高效，尤其适合微服务架构和前后端分离项目。
Springboot 3项目整合Knife4j接口文档（接口分组详细教程）
桃吱咬咬_的博客
07-08 9292
本文介绍了Spring Boot 3.0整合Knife4j的方法，并对比了Swagger 2与OpenAPI 3的注解差异。Spring Boot 3.0仅支持OpenAPI 3规范，推荐使用springdoc-openapi或Knife4j（基于springdoc）。文章详细说明了版本兼容性、配置步骤及常见问题解决方案，包括依赖导入、yml配置、WebMvc静态资源放行等，帮助开发者顺利迁移至OpenAPI 3规范并生成API文档。
Spring Boot3整合knife4j(swagger3)
蒾酒的博客
01-23 7556
Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j (xiaominfo.com)作者的使用的spring boot 3.2.2为当前最新版，所以依赖导入最新的knife4j 4.4.0。3.1 增强模式 | Knife4j (xiaominfo.com)好一个spring boot项目且版本为3X，项目可正常启动。快速开始 | Knife4j (xiaominfo.com)接下来配置以下接口文档的作者等信息。@Tag注解：标记接口类别。
最完整版-Springboot3集成Knife4j
学习记录
08-22 9261
在使用时我觉得它的样式和蓝色主色调不符合我的审美，所以我觉得使用一个更强的工具Knife4j。Knife4j是一个用于SpringBoot和SpringCloud的增强Swagger的工具，提供黑色主题和更多配置选项。Knife4j在更名之前，原来的名称是叫swagger-bootstrap-ui，这是两种不一样风格的ui显示，将原来的蓝色变成炫酷的黑色模式。二，Knife4j和swagger-bootstrap-ui对比工具状态风格配置Knife4j持久更新黑色主题支持配置文件编写配置项。
springboot3整合knife4j详细版，包会！（不带swagger2玩）
qq_51774011的博客
07-21 7789
springboot3在整合swagger2或者3时均不太好使，而且swagger的默认ui页面真的一言难尽，官方现在推荐使用springdoc-openapi集成接口文档，但是经过测试一些注解个性化文档时存在不好使的情况，而且ui界面依然感觉不好看。本文详细记录了knife4j集成接口文档的详细使用步骤，配置详解以及注解详解。绝对是up亲身测验过的，绝对好用！！！百度了很多内容，踩了很多坑后的整理版。
springboot3整合swagger3.0之knife4j-openapi3
施小楠的博客
10-09 2039
markdown文件路径,可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md)针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点。是否开启一个默认的跨域配置,该功能配合自定义Host使用。调试Tab是否显示AfterScript功能,默认开启。类似于接口中的tag,对于自定义文档的分组。
SpringBoot3快速整合Swagger和knife4j
m0_61591135的博客
01-25 665
SpringBoot整合Swagger和Knif4j
Spring Boot 3 集成 Knife4j
晶谛-giserDev
11-22 2864
Spring Boot 3 集成 Knife4j
SpringBoot3整合Knife4j
市民景先生
02-11 1579
ps：json处理需要引入相关包packages-to-scan: com.xiaominfo.knife4j.demo.web#需要改位置地址/doc.html。
SPringboot3整合knife4j
qq_75269496的博客
07-08 835
springboot整合knife4j快速入门，跟着教程一遍过，以及自己在初次使用时的一些问题。
springboot3 集成 knife4j（接口文档）
01-23 1384
提示：：大家在开发阶段，前后端对接时，一份简洁明了的接口文档，至关重要，本文讲述了在 springboot3 的框架下，如何快速集成 knife4j。knife4j 并非只有这几个注解，我是挑选了几个最重要的，而且也基本能满足大家日常开发需求，如果需要更详细的可以跳转knife4j 官网。
springboot3 集成knife4j
一个写了10年bug的程序员日常笔记。
04-22 1909
Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案。Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4jjava：17。
springboot3整合knife4j（swagger增强）
LB_bei的博客
01-15 1654
springboot升级到3后之前的knife4j配置就要变了一下了。
SpringBoot3整合Knife4j实战
qq_48428343的博客
06-12 1308
在日常开发中，写接口文档是我们必不可少的，而Knife4j就是一个接口文档工具，可以看作是Swagger的升级版，但是界面比Swagger更好看，功能更丰富。
springboot3以上knife4j起步依赖使用
03-01
### Spring Boot 3+ Knife4j 起步依赖配置及使用方法 #### 一、引入依赖 对于Spring Boot 3及以上版本，为了成功整合Knife4j并生成API文档，需在`pom.xml`文件中加入特定的Maven依赖。考虑到Swagger2不再支持Spring Boot 3，应选用基于OpenAPI 3标准的组件——即knife4j-openapi3。 ```xml <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency> <!-- 如果需要更全面的功能 --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.14</version> </dependency> ``` 上述代码展示了如何向项目添加必要的库以启用Knife4j功能[^3]。 #### 二、编写配置类 创建一个新的Java类用于定义Bean实例和其他设置项，以便更好地控制API文档的行为特性。此类通常命名为类似于`SwaggerConfig.java`： ```java import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration @EnableKnife4j public class SwaggerConfig { @Bean(value = "defaultApi2") public Docket defaultApi2() { return new Docket(DocumentationType.OAS_30) .apiInfo(new ApiInfoBuilder() .title("Your Project API Documentation") // 文档标题 .description("This is a demo project for spring boot and knife4j.") // 描述 .contact(new Contact("Author Name", "", "")) .version("1.0") .build()) .select() .apis(RequestHandlerSelectors.basePackage("your.controller.package")) .paths(PathSelectors.any()) .build(); } } ``` 此部分代码实现了对API信息的基本描述以及路径的选择规则设定[^1]。 #### 三、访问API文档界面 完成以上两步操作之后，在应用程序运行状态下打开浏览器，并输入如下URL即可查看由Knife4j渲染后的交互式API文档页面： - `http://localhost:8080/doc.html` 该链接指向了一个集成了多种特性的在线编辑器环境，允许开发者轻松浏览已发布的RESTful服务端点及其参数详情[^5]。
评论 1
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值