springboot2与springboot3集成Knife4j

xintgong

于 2024-10-07 22:14:58 发布

阅读量1k

点赞数 8

本文链接：https://blog.csdn.net/xintgong/article/details/142747039

版权

springboot2与springboot3集成Knife4j

1.什么是Knife4j

Knife4j 是一个基于 Swagger 的增强型 API 文档生成工具。它扩展了 Swagger 提供的功能，为开发者提供了更加丰富和直观的 API 文档展示。相比于原生的 Swagger UI，Knife4j 提供了更多的界面定制、文档分组、参数说明和请求头配置等功能，极大地提升了 API 文档的可读性和使用体验。主要有以下优势：

UI 界面优化：相比 Swagger 原生的界面，Knife4j 提供了更简洁、用户友好的界面。
参数支持更丰富：包括对请求头、请求体、路径参数等的更详细展示。
分组功能：可以方便地对不同的 API 进行分组管理，尤其适用于大规模 API 项目。
动态请求测试：支持在文档中直接测试 API，模拟请求和查看响应。

官方文档：https://doc.xiaominfo.com/
在这里插入图片描述
Knife4j 可以很容易地集成到 Spring Boot 项目中，下面将介绍如何分别在 Spring Boot 2 和 Spring Boot 3 项目中集成。

2. Spring Boot 2 集成 Knife4j

1. 引入maven依赖

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

2.配置文件

knife4j:
  enable: true  # 启用 Knife4j

3. swagger配置类

@Configuration
@Slf4j
public class SwaggerConfig {
/**
    * 通过knife4j生成接口文档
    * @return
    */
   @Bean
   public Docket docket() {
       ApiInfo apiInfo = new ApiInfoBuilder()
               .title("项目接口文档")
               .version("2.0")
               .description("项目接口文档")
               .build();
       Docket docket = new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo)
               .select()
               .apis(RequestHandlerSelectors.basePackage(包路径))
               .paths(PathSelectors.any())
               .build();
       return docket;
   }

   /**
    * 设置静态资源映射
    * @param registry
    */
   protected void addResourceHandlers(ResourceHandlerRegistry registry) {
       registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
       registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
   }
   }
}

4.常用注解

注解	说明
@Api	用在类上，例如Controller，表示对类的说明
@ApiModel	用在类上，例如entity、DTO、VO
@ApiModelProperty	用在属性上，描述属性信息
@ApiOperation	用在方法上，例如Controller的方法，说明方法的用途、作用

使用示例：

@Data
@ApiModel(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;

}

/**
 * 员工管理
 */
@Api(tags = "员工相关接口")
public class EmployeeController {
    /**
     * 登录
     *
     * @param employeeLoginDTO
     * @return
     */
    @PostMapping("/login")
    @ApiOperation("员工登录")
    public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO) { 
        return Result.success(employeeLoginVO);
    }
    /**
     * 退出
     *
     * @return
     */
    @ApiOperation("员工退出登录")
    @PostMapping("/logout")
    public Result<String> logout() {
        return Result.success();
    }
}

5. 访问 Knife4j 界面
启动项目后，访问 http://localhost:8080/doc.html 即可看到 Knife4j 的界面。

3. springboot3 集成Knife4j

1. 引入maven依赖

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

2.配置文件

# Knife4j配置
# springdoc-openapi配置
springdoc:
  # get请求多参数时不需要添加额外的@ParameterObject和@Parameter注解
  default-flat-param-object: true
  # 启用swaggerUI
  swagger-ui:
    #自定义swagger前端请求路径，输入http：127.0.0.1:8080/swagger-ui.html会自动重定向到swagger页面
    path: /swagger-ui.html
    enabled: true
    operations-sorter: order 
  # 启用文档，默认开启
  api-docs:
    path: /v3/api-docs    #swagger后端请求地址
    enabled: true


# knife4j相关配置
knife4j:
  enable: true    #开启knife4j
  setting:
    language: 'zh-CN'   # 中文:ZH_CN 英文:EN
    enable-swagger-models: true
    swagger-model-name: 实体列表
    enable-dynamic-parameter: false
    enable-footer-custom: true
    enable-footer: true
    enable-document-manage: true
  basic:
    enable: true
    username: admin
    password: 123456

3.配置类

/**
 * Knife4j整合Swagger3 Api接口文档配置类
 */
@Configuration
public class Knife4jConfig {

   /**
    * 创建了一个api接口的分组
    * 除了配置文件方式创建分组，也可以通过注册bean创建分组
    */
   @Bean
   public GroupedOpenApi adminApi() {
       return GroupedOpenApi.builder()
               // 分组名称
               .group("app-api")
               // 接口请求路径规则
               .pathsToMatch("/**")
               .build();
   }

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

4.常用注解

注解	说明
@Tag	用在类上，例如Controller，表示对类的说明
@Schema	用在类上，例如entity、DTO、VO
@Operation	用在方法上，例如Controller的方法，说明方法的用途、作用

使用示例：

@Data
@Schema(name ="用户登录数据模型" )
public class UserDto {
    @Schema(name = "用户名",description = "用户名",example = "admin")
    private String userName;

    @Schema(name = "密码",description = "密码",example = "123456")
    private String password;

    @Schema(name = "验证码",description = "验证码")
    private String code;

    @Schema(name = "uuid",description = "uuid")
    private String uuid;


}

@RestController
@Tag(name = "测试接口")
public class TestController {
    @Autowired
    private LoginService loginService;

    @PostMapping("/login")
    @Operation(summary = "登录接口")
    public Result login(@RequestBody UserDto userDto) {
        return loginService.login(userDto);
    }
   }