SpringBoot3整合Knife4j实战

文章目录

前言

一、SpringBoot版本对应的Knife4j版本

二、使用步骤

1. 导入knife4j-openAPI3依赖

2.配置application.yml文件

3. controller类中使用注解@Tag、@Operation和@RequestParam注解。

4. 项目启动成功

前言

在日常开发中，写接口文档是我们必不可少的，而Knife4j就是一个接口文档工具，可以看作是Swagger的升级版，但是界面比Swagger更好看，功能更丰富。

一、SpringBoot版本对应的Knife4j版本

首先，确保您了解您的项目所使用的Spring Boot版本。以下是一些常见的Spring Boot版本及其对应的Knife4j版本兼容推荐：

本文以为SpringBoot3为例：

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

二、使用步骤

1. 导入knife4j-openAPI3依赖

代码如下：

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

2.配置application.yml文件

代码如下：

注意：只需要修改packages-to-scan，设置为自己controller文件下的路径

# 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: org.example.controller
 #knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn
  production: false

3. controller类中使用注解@Tag、@Operation和@RequestParam注解。

@Tag

用于说明或定义的标签，作用域controller类。
部分参数：
●name：名称
●description：描述

@Operation

描述 API 操作的元数据信息，作用域controller类中的方法。
●summary：简短描述
●description ：更详细的描述
●hidden：是否隐藏
●tags：标签，用于分组API
●operationId：操作的唯一标识符，建议使用唯一且具有描述性的名称
●parameters：指定相关的请求参数，使用 @Parameter 注解来定义参数的详细属性。
●requestBody：指定请求的内容，使用 @RequestBody 注解來指定请求的类型。
●responses：指定操作的返回内容，使用 @ApiResponse 注解定义返回值的详细属

@Parameter

用于描述 API 操作中的参数 部分参数：
●name : 指定的参数名
●in：参数来源，可选 query、header、path 或 cookie，默认为空，表示忽略
        ○ParameterIn.QUERY 请求参数
        ○ParameterIn.PATH 路径参数
        ○ParameterIn.HEADER header参数
        ○ParameterIn.COOKIE cookie 参数
●description：参数描述
●required：是否必填，默认为 false
●schema ：参数的数据类型。如 schema = @Schema(type = "string")

@Parameters（作用于controller方法）

包含多个 @Parameter 注解，指定多个参数。 代码参考： 包含了 param1 和 param2 两个参数

@Parameters({
  @Parameter(
    name = "param1",
    description = "Parameter 1 description",
    required = true,
    in = ParameterIn.PATH,
    schema = @Schema(type = "string")
  ),
  @Parameter(
    name = "param2",
    description = "Parameter 2 description",
    required = true,
    in = ParameterIn.QUERY,
    schema = @Schema(type = "integer")
  )
})

4. 项目启动成功