SpringBoot接口文档自动化：Swagger3与Knife4j的完美融合

最新推荐文章于 2026-08-13 09:48:04 发布

原创最新推荐文章于 2026-08-13 09:48:04 发布 · 1k 阅读

27 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

Web

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

SpringBoot接口文档自动化：Swagger3与Knife4j的完美融合

一、引言

在当今的软件开发过程中，接口文档的重要性不言而喻。它不仅是前后端开发人员之间沟通的桥梁，也是测试人员进行接口测试的依据。然而，传统的手动编写接口文档的方式效率低下，且容易出错，随着项目的不断迭代，文档的更新也变得十分繁琐。为了解决这些问题，接口文档自动化工具应运而生。Swagger 作为一款流行的接口文档生成工具，能够自动生成详细的接口文档，大大提高了开发效率。而 Knife4j 则是对 Swagger 的增强，提供了更加美观、易用的界面。本文将详细介绍如何在 Spring Boot 项目中实现 Swagger3 与 Knife4j 的完美融合，实现接口文档的自动化生成。

二、Swagger3 和 Knife4j 简介

2.1 Swagger3

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger3 是 Swagger 的最新版本，它基于 OpenAPI 3.0 规范，提供了更加强大的功能和更好的性能。Swagger3 可以通过注解的方式自动生成接口文档，开发人员只需要在代码中添加相应的注解，就可以轻松生成详细的接口文档。

2.2 Knife4j

Knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案。它在 Swagger 的基础上进行了优化和扩展，提供了更加美观、易用的界面，支持离线文档、接口排序、参数验证等功能。Knife4j 可以帮助开发人员更好地管理和查看接口文档，提高开发效率。

三、环境准备

在开始集成 Swagger3 和 Knife4j 之前，需要确保已经具备以下环境：

Java 8 或以上版本
Spring Boot 2.3.x 或以上版本
Maven 或 Gradle 构建工具

3.1 创建 Spring Boot 项目

可以使用 Spring Initializr（https://start.spring.io/）来快速创建一个 Spring Boot 项目。在创建项目时，选择以下依赖：

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

3.2 添加依赖

如果使用 Maven 构建项目，在 pom.xml 中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

如果使用 Gradle 构建项目，在 build.gradle 中添加以下依赖：

implementation 'io.springfox:springfox-boot-starter:3.0.0'
implementation 'com.github.xiaoymin:knife4j-spring-boot-starter:3.0.3'

四、配置 Swagger3

4.1 创建 Swagger 配置类

在项目中创建一个 Swagger 配置类，用于配置 Swagger3 的相关信息。以下是一个示例配置类：

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.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 Swagger3 接口文档")
               .description("这是一个使用 Swagger3 和 Knife4j 生成的接口文档示例")
               .version("1.0.0")
               .build();
    }
}

在上述代码中，@Configuration 注解表示这是一个配置类，@EnableOpenApi 注解用于启用 Swagger3。Docket 是 Swagger 的核心配置类，通过 apiInfo() 方法设置接口文档的基本信息，通过 select() 方法选择要生成文档的接口。

4.2 配置扫描路径

在 Docket 的 apis() 方法中，通过 RequestHandlerSelectors.basePackage() 方法指定要扫描的控制器包路径。只有在该路径下的控制器才会生成接口文档。

五、使用 Swagger 注解

5.1 控制器注解

在控制器类上使用 @Api 注解，用于描述该控制器的功能。例如：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Tag(name = "用户管理", description = "用户管理相关接口")
public class UserController {

    @GetMapping("/user")
    @Operation(summary = "获取用户信息", description = "根据用户 ID 获取用户信息")
    public String getUser() {
        return "User information";
    }
}

在上述代码中，@Tag 注解用于描述控制器的功能，@Operation 注解用于描述接口的功能。

5.2 参数注解

在接口方法的参数上使用 @Parameter 注解，用于描述参数的信息。例如：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Tag(name = "用户管理", description = "用户管理相关接口")
public class UserController {

    @GetMapping("/user")
    @Operation(summary = "获取用户信息", description = "根据用户 ID 获取用户信息")
    public String getUser(@Parameter(name = "userId", description = "用户 ID", required = true) @RequestParam String userId) {
        return "User information for ID: " + userId;
    }
}

在上述代码中，@Parameter 注解用于描述 userId 参数的信息。

5.3 响应注解

在接口方法上使用 @ApiResponse 注解，用于描述接口的响应信息。例如：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Tag(name = "用户管理", description = "用户管理相关接口")
public class UserController {

    @GetMapping("/user")
    @Operation(summary = "获取用户信息", description = "根据用户 ID 获取用户信息")
    @ApiResponse(responseCode = "200", description = "成功获取用户信息")
    public String getUser(@Parameter(name = "userId", description = "用户 ID", required = true) @RequestParam String userId) {
        return "User information for ID: " + userId;
    }
}

在上述代码中，@ApiResponse 注解用于描述接口的响应信息。

六、集成 Knife4j

6.1 配置 Knife4j

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

knife4j.enable=true

knife4j:
  enable: true

上述配置用于启用 Knife4j。

6.2 访问 Knife4j 界面

启动 Spring Boot 项目后，访问以下地址即可查看 Knife4j 生成的接口文档：

http://localhost:8080/doc.html

在 Knife4j 界面中，可以查看详细的接口文档信息，包括接口的基本信息、请求参数、响应信息等。同时，还可以进行接口测试，方便开发人员进行调试。

七、高级配置

7.1 分组管理

在 Swagger 配置类中，可以通过创建多个 Docket 实例来实现接口的分组管理。例如：

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.OAS_30)
               .groupName("用户管理")
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.user"))
               .paths(PathSelectors.any())
               .build();
    }

    @Bean
    public Docket orderApi() {
        return new Docket(DocumentationType.OAS_30)
               .groupName("订单管理")
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.order"))
               .paths(PathSelectors.any())
               .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
               .title("Spring Boot Swagger3 接口文档")
               .description("这是一个使用 Swagger3 和 Knife4j 生成的接口文档示例")
               .version("1.0.0")
               .build();
    }
}

在上述代码中，通过创建两个 Docket 实例，分别对用户管理和订单管理的接口进行分组。

7.2 安全配置

如果接口需要进行身份验证，可以在 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.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Arrays;
import java.util.List;

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
               .apiInfo(apiInfo())
               .securityContexts(Arrays.asList(securityContext()))
               .securitySchemes(Arrays.asList(apiKey()))
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.any())
               .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
               .title("Spring Boot Swagger3 接口文档")
               .description("这是一个使用 Swagger3 和 Knife4j 生成的接口文档示例")
               .version("1.0.0")
               .build();
    }

    private ApiKey apiKey() {
        return new ApiKey("Authorization", "Authorization", "header");
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
               .securityReferences(defaultAuth())
               .forPaths(PathSelectors.any())
               .build();
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference("Authorization", authorizationScopes));
    }
}

在上述代码中，通过 apiKey() 方法配置了一个 Authorization 头信息的认证方式，通过 securityContext() 方法和 defaultAuth() 方法配置了安全上下文。

八、总结

通过本文的介绍，我们了解了如何在 Spring Boot 项目中实现 Swagger3 与 Knife4j 的完美融合，实现接口文档的自动化生成。Swagger3 提供了强大的接口文档生成功能，而 Knife4j 则在 Swagger 的基础上进行了优化和扩展，提供了更加美观、易用的界面。通过使用 Swagger 注解，可以轻松地对接口进行描述，提高接口文档的可读性和可维护性。同时，还介绍了一些高级配置，如分组管理和安全配置，帮助开发人员更好地管理和保护接口。希望本文对大家在实际项目中使用 Swagger3 和 Knife4j 有所帮助。

标签

#spring boot #自动化 #后端