Knife4j 快速上手指南，用注解定义清晰接口文档

2023-04-22 13:50:48

API 文档：为开发人员提供清晰的蓝图

构建大型软件系统时，API 文档对于开发者来说至关重要。它提供了一个清晰的指南，帮助他们快速理解和使用系统，从而提高开发效率。

Spring Boot 与 Knife4j：无缝生成 API 文档

Knife4j 是一个基于 Swagger 的 API 文档生成工具，它提供了一种便捷的方法来为 Spring Boot 项目生成在线 API 文档。将 Knife4j 集成到 Spring Boot 项目的步骤如下：

添加依赖项：

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

配置 application.yml：

knife4j:
  enable: true

启动项目：

mvn spring-boot:run

访问在线 API 文档：

打开浏览器，输入 http://localhost:8080/doc.html，即可查看在线 API 文档。

Api 注解和 @ApiOperation 注解： API 的强大工具

Api 注解用于 API 接口的基本信息，包括接口名称、标签等。它可以应用于 Controller 类或方法上，分别用于描述整个 Controller 或单个方法。

@ApiOperation 注解用于描述 API 接口的操作，包括接口名称、描述、响应信息等。

示例：

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

    @PostMapping("/user")
    @ApiOperation(value = "创建用户", notes = "创建新的用户")
    public User createUser(@RequestBody User user) {
        return userService.create(user);
    }

    @GetMapping("/user/{id}")
    @ApiOperation(value = "获取用户", notes = "根据用户 ID 获取用户")
    public User getUser(@PathVariable("id") Long id) {
        return userService.get(id);
    }
}