Knife4j快速入门指南：Spring Boot项目集成OpenAPI文档

郑眉允Well-Born

于 2025-06-09 09:21:24 发布

阅读量355

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_01174/article/details/148527233

Knife4j快速入门指南：Spring Boot项目集成OpenAPI文档

knife4j Knife4j is a set of Swagger2 and OpenAPI3 All-in-one enhancement solution 项目地址: https://gitcode.com/gh_mirrors/kn/knife4j

项目简介

Knife4j是一款基于OpenAPI规范的API文档增强工具，专为Java开发者设计，尤其适合Spring Boot项目。它能够自动生成美观、交互性强的API文档界面，并提供多种增强功能，帮助开发者更高效地管理和测试接口。

环境准备

在开始集成Knife4j之前，请确保您的开发环境满足以下要求：

JDK版本：根据Spring Boot版本选择
- Spring Boot 3.x：JDK 17+
- Spring Boot 2.x：JDK 8+
Spring Boot版本：
- 推荐Spring Boot 2.4.0及以上版本
- 最新版本支持Spring Boot 3.x

Spring Boot 3.x集成指南

依赖配置

对于Spring Boot 3.x项目，Knife4j提供了专门的starter包：

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

基础配置

在application.yml中添加以下配置：

springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.example.package

knife4j:
  enable: true
  setting:
    language: zh_cn

接口注解示例

使用OpenAPI 3规范注解您的Controller：

@RestController
@RequestMapping("/api")
@Tag(name = "用户管理", description = "用户相关操作接口")
public class UserController {
    
    @Operation(summary = "获取用户详情")
    @Parameters({
        @Parameter(name = "userId", description = "用户ID", required = true)
    })
    @GetMapping("/users/{userId}")
    public ResponseEntity<User> getUser(@PathVariable Long userId) {
        // 业务逻辑
    }
}

Spring Boot 2.x集成指南

Spring Boot 2.x项目可以选择支持OpenAPI 2或OpenAPI 3规范。

OpenAPI 2规范集成

依赖配置

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

基础配置

knife4j:
  enable: true
  openapi:
    title: API文档
    description: 系统接口文档
    version: 1.0.0
    group:
      default:
        group-name: 默认分组
        api-rule: package
        api-rule-resources: com.example.controller

OpenAPI 3规范集成

依赖配置

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

配置方式与Spring Boot 3.x相同。

文档访问

完成上述配置后，启动应用，可以通过以下地址访问文档：

默认文档地址：http://localhost:8080/doc.html
原生Swagger UI地址：http://localhost:8080/swagger-ui.html

最佳实践建议

版本选择：
- 新项目建议直接使用Spring Boot 3.x + OpenAPI 3规范
- 已有项目可根据实际情况选择OpenAPI 2或3规范
分组配置：
- 大型项目建议按模块分组管理接口
- 可以通过配置多个group实现多分组文档
注解使用：
- 为每个Controller添加@Tag注解，明确模块划分
- 为每个接口方法添加@Operation注解，详细描述功能
- 使用@Parameter注解明确参数说明和约束
生产环境：
- 建议通过配置动态控制文档的开启/关闭
- 可结合Spring Security进行访问权限控制