轻松实现！Springboot集成knife4j接口文档显示攻略

2023-11-25 01:13:30

通过 Knife4j 轻松生成美观的 API 文档

简介

在现代软件开发中，API 文档对于有效沟通和了解应用程序的功能至关重要。Knife4j 是一个开源工具，可以帮助开发人员快速、轻松地生成美观的在线 API 文档。

集成

集成 Knife4j 非常简单。对于 Spring Boot 应用程序，只需将以下依赖项添加到您的 pom.xml 文件中：

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

然后在 application.yml 文件中启用 Knife4j：

knife4j:
  enable: true

使用

要为您的 API 接口生成文档，请使用以下注解：

@ApiOperation：操作。
@ApiImplicitParam：指定请求参数。
@ApiResponse：指定响应类型。

例如：

@ApiOperation(value = "获取用户列表")
@GetMapping("/users")
public List<User> getUsers() {
  return userService.getUsers();
}

高级用法

分组

您可以使用 @Api 注解对您的接口进行分组。例如：

@Api(value = "用户管理", tags = {"用户"})
public class UserController {

  @ApiOperation(value = "获取用户列表")
  @GetMapping("/users")
  public List<User> getUsers() {
    return userService.getUsers();
  }
}

参数类型

@ApiImplicitParam 注解可用于指定请求参数的类型：

@ApiOperation(value = "获取用户详情")
@GetMapping("/users/{id}")
public User getUser(@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long") Long id) {
  return userService.getUser(id);
}

响应类型

@ApiResponse 注解可用于指定响应类型：

@ApiOperation(value = "删除用户")
@DeleteMapping("/users/{id}")
@ApiResponses(value = {
  @ApiResponse(code = 200, message = "成功"),
  @ApiResponse(code = 404, message = "用户不存在")
})
public void deleteUser(@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long") Long id) {
  userService.deleteUser(id);
}