Spring Boot整合Knife4j

简介

在Spring Boot项目中，使用Knife4j可以快速、方便地生成接口文档。本文将介绍如何在Spring Boot项目中整合Knife4j，并详细说明每一步需要做什么以及相应的代码。

整合步骤

下面的表格展示了整个整合Knife4j的步骤：

步骤 描述
1 添加Knife4j依赖
2 配置Knife4j
3 编写接口文档注解
4 启动项目并访问接口文档

下面将逐步详细说明每一步需要做什么，以及相应的代码。

步骤1：添加Knife4j依赖

在Spring Boot的pom.xml文件中添加以下依赖：

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

这样就引入了Knife4j的依赖。

步骤2：配置Knife4j

在Spring Boot的配置类中添加Knife4j的配置：

@Configuration
@EnableSwagger2
public class Knife4jConfiguration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("这是一个示例API文档")
                .version("1.0")
                .build();
    }
}

这个配置类使用@EnableSwagger2注解启用Knife4j，并通过createRestApi方法创建一个Docket对象，用来配置接口文档的基本信息，如标题、描述和版本等。在ApiInfo中可以设置更多的配置项。

在createRestApi方法中，.apis(RequestHandlerSelectors.basePackage("com.example.controller"))用于指定扫描的Controller所在的包路径，你需要将com.example.controller替换为你的实际包路径。

步骤3：编写接口文档注解

在你的Controller类中，通过添加Knife4j的注解来生成接口文档。以下是一些常用的注解：

  • @ApiOperation：用于描述接口的作用和说明。
  • @ApiParam：用于描述接口参数的说明。
  • @ApiModel：用于描述接口返回结果的说明。
  • @ApiModelProperty：用于描述接口返回结果中的字段说明。

示例：

@RestController
@Api(tags = "用户管理")
@RequestMapping("/user")
public class UserController {

    @ApiOperation("获取用户列表")
    @GetMapping("/list")
    public List<User> getUserList() {
        // 返回用户列表
    }

    @ApiOperation("添加用户")
    @PostMapping("/add")
    public void addUser(@ApiParam("用户信息") @RequestBody User user) {
        // 添加用户
    }

    // 其他接口...
}

在上面的示例中，@Api(tags = "用户管理")用于设置接口所属的标签，@ApiOperation用于描述接口的作用，@ApiParam用于描述接口参数的说明。

步骤4：启动项目并访问接口文档

编译并启动Spring Boot项目后，访问以下路径即可查看生成的接口文档：

http://localhost:8080/doc.html

关系图

下面使用mermaid语法展示一个简单的关系图，示意Spring Boot整合Knife4j的流程：

erDiagram
    SpringBoot -.- Knife4j: 包含
    SpringBoot -.-> Controller: 包含
    Controller -.-> Swagger2: 使用

总结

通过上述步骤，我们成功地实现了Spring Boot整合Knife4j的过程。首先添加Knife4j的依赖，然后配置Knife4j的基本信息，接着在Controller中添加Knife4j的注解，最后启动项目并访问生成的接口文