🎓博主介绍：Java、Python、js全栈开发 “多面手”，精通多种编程语言和技术，痴迷于人工智能领域。秉持着对技术的热爱与执着，持续探索创新，愿在此分享交流和学习，与大家共进步。
📖DeepSeek-行业融合之万象视界(附实战案例详解100+)
📖全栈开发环境搭建运行攻略：多语言一站式指南(环境搭建+运行+调试+发布+保姆级详解)
👉感兴趣的可以先收藏起来，希望帮助更多的人

SpringBoot接口文档自动化：Swagger3+Knife4j最佳实践

一、引言

在当今的软件开发过程中，接口文档的重要性不言而喻。它不仅是前后端开发人员沟通的桥梁，也是测试人员进行接口测试的依据。传统的手动编写接口文档的方式不仅效率低下，而且容易出现文档与实际接口不一致的问题。为了解决这些问题，自动化接口文档工具应运而生。Swagger 是一个强大的接口文档生成工具，而 Knife4j 则是在 Swagger 基础上进行增强的 UI 框架，它们的结合可以为 Spring Boot 项目提供高效、美观的接口文档解决方案。本文将详细介绍如何在 Spring Boot 项目中使用 Swagger3 和 Knife4j 实现接口文档的自动化生成。

二、Swagger3 和 Knife4j 简介

2.1 Swagger3

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger3 是 Swagger 的最新版本，它基于 OpenAPI 3.0 规范，提供了更强大的功能和更好的兼容性。Swagger 可以自动生成接口文档，并且支持在线测试接口，大大提高了开发效率。

2.2 Knife4j

Knife4j 是为 Swagger 增强的 UI 框架，它对 Swagger 的默认 UI 进行了优化和美化，提供了更友好的用户界面和更丰富的功能。Knife4j 支持接口文档的分组、搜索、离线文档生成等功能，让接口文档的查看和使用更加方便。

三、Spring Boot 项目集成 Swagger3 和 Knife4j

3.1 创建 Spring Boot 项目

首先，我们需要创建一个新的 Spring Boot 项目。可以使用 Spring Initializr（https://start.spring.io/）来快速创建项目，选择以下依赖：

• Spring Web
• Lombok（可选，用于简化 Java 代码）

3.2 添加依赖

在项目的 pom.xml 文件中添加 Swagger3 和 Knife4j 的依赖：

<dependencies>
    <!-- Swagger3 依赖 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
    <!-- Knife4j 依赖 -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>4.1.0</version>
    </dependency>
</dependencies>

3.3 配置 Swagger3

创建一个 Swagger 配置类，用于配置 Swagger 的相关信息：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 指定扫描的控制器包
               .paths(PathSelectors.any())
               .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
               .title("Spring Boot 接口文档")
               .description("使用 Swagger3 和 Knife4j 生成的接口文档")
               .contact(new Contact("Your Name", "https://yourwebsite.com", "your.email@example.com"))
               .version("1.0.0")
               .build();
    }
}

3.4 配置 Knife4j

在 application.properties 或 application.yml 中添加 Knife4j 的配置：

# 开启 Knife4j 增强功能
knife4j.enable=true

3.5 编写控制器

创建一个简单的控制器类，用于测试接口文档的生成：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Api(tags = "测试接口")
public class TestController {

    @GetMapping("/hello")
    @ApiOperation("获取问候语")
    public String hello() {
        return "Hello, World!";
    }
}

3.6 启动项目并访问接口文档

启动 Spring Boot 项目，访问 http://localhost:8080/doc.html 即可看到 Knife4j 生成的接口文档页面。在该页面中，可以查看接口的详细信息，并且可以在线测试接口。

四、Swagger3 注解的使用

4.1 @Api 注解

@Api 注解用于标记控制器类，为该类生成的接口文档添加分组信息。例如：

@RestController
@RequestMapping("/api")
@Api(tags = "用户管理接口")
public class UserController {
    // 控制器方法
}

4.2 @ApiOperation 注解

@ApiOperation 注解用于标记控制器方法，为该方法生成的接口文档添加描述信息。例如：

@GetMapping("/users")
@ApiOperation("获取所有用户信息")
public List<User> getUsers() {
    // 方法实现
    return userService.getUsers();
}

4.3 @ApiParam 注解

@ApiParam 注解用于标记方法参数，为该参数生成的接口文档添加描述信息。例如：

@GetMapping("/users/{id}")
@ApiOperation("根据用户 ID 获取用户信息")
public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable Long id) {
    // 方法实现
    return userService.getUserById(id);
}

4.4 @ApiModel 和 @ApiModelProperty 注解

@ApiModel 注解用于标记实体类，为该类生成的接口文档添加描述信息。@ApiModelProperty 注解用于标记实体类的属性，为该属性生成的接口文档添加描述信息。例如：

@ApiModel("用户信息")
public class User {
    @ApiModelProperty("用户 ID")
    private Long id;
    @ApiModelProperty("用户姓名")
    private String name;
    // 省略 getter 和 setter 方法
}

五、Knife4j 高级功能

5.1 接口文档分组

Knife4j 支持接口文档的分组功能，可以将不同的接口划分到不同的组中，方便查看和管理。可以通过在 @Api 注解中设置 tags 属性来实现接口分组。例如：

@RestController
@RequestMapping("/api")
@Api(tags = "用户管理接口")
public class UserController {
    // 用户管理接口方法
}

@RestController
@RequestMapping("/api")
@Api(tags = "订单管理接口")
public class OrderController {
    // 订单管理接口方法
}

5.2 离线文档生成

Knife4j 支持离线文档生成功能，可以将接口文档导出为 HTML、PDF 等格式。在 Knife4j 文档页面中，点击右上角的“离线文档”按钮，选择相应的格式进行导出。

5.3 接口搜索

Knife4j 提供了接口搜索功能，可以通过关键词快速搜索到需要的接口。在文档页面的搜索框中输入关键词，即可筛选出包含该关键词的接口。

六、注意事项

6.1 生产环境禁用 Swagger

Swagger 会暴露项目的接口信息，为了安全起见，在生产环境中应该禁用 Swagger。可以通过配置文件来实现：

# 生产环境禁用 Swagger
springfox.documentation.enabled=false

6.2 版本兼容性

在使用 Swagger3 和 Knife4j 时，需要注意版本的兼容性。不同版本的 Swagger 和 Knife4j 可能会存在一些兼容性问题，建议使用官方推荐的版本。

七、总结

通过本文的介绍，我们学习了如何在 Spring Boot 项目中集成 Swagger3 和 Knife4j 实现接口文档的自动化生成。Swagger3 提供了强大的接口文档生成功能，而 Knife4j 则对 Swagger 的 UI 进行了优化和增强，让接口文档的查看和使用更加方便。同时，我们还介绍了 Swagger3 注解的使用和 Knife4j 的高级功能，以及一些注意事项。希望本文对你在 Spring Boot 项目中使用 Swagger3 和 Knife4j 有所帮助。