Knife4j-OpenAPI3 简单使用（通俗易懂版）
Knife4j 是一个基于 Swagger 的增强工具，旨在提供美观的 API 文档展示和更便捷的使用。
1. 什么是 Knife4j？
Knife4j 是一个 Java 生态中开源的文档生成工具，特别适合对于 Spring Boot 项目中的 RESTful API 进行文档展示。它可以帮助开发者轻松快速地生成丰富的 API 文档，支持多种格式的输出，同时具备良好的用户体验。
2. 为什么使用 Knife4j？
- 简化 API 文档生成：通过注解的方式自动生成文档，减少手动维护成本。
- 美观的界面：提供用户友好的文档展示界面。
- 丰富的功能：支持 OAuth2、JWT 等认证特性，能够实现自定义接口调用。
3. Knife4j 的适用场景
如果你的项目使用了 Spring Boot，且需要生成 RESTful API 文档，Knife4j 是一个非常实用的选择。特别是当你需要与同事或客户分享接口文档时，全面而美观的文档会更具说服力。
4. Knife4j 的基本使用步骤
4.1 添加依赖
首先，在你的 Spring Boot 项目的 pom.xml 文件中添加 Knife4j 的依赖：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version> <!-- 请确认使用最新版本 -->
</dependency>
如果你在使用 Gradle，可以使用以下方式：
implementation 'com.github.xiaoymin:knife4j-spring-boot-starter:3.0.3'
4.2 配置 Knife4j
在 application.yml 或 application.properties 文件中添加以下配置：
knife4j:
enabled: true
path: /doc.html
这将使 Knife4j 的文档访问地址为 http://localhost:8080/doc.html。
4.3 编写 API
现在，我们来编写一个简单的 RESTful API，使用 Swagger 注解来描述 API 接口。例如，我们创建一个 UserController：
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
@RestController
@RequestMapping("/users")
@Api(tags = "用户管理接口")
public class UserController {
private List<User> userList = new ArrayList<>();
@GetMapping
@ApiOperation(value = "获取所有用户", notes = "此接口用于获取所有用户信息")
public List<User> getAllUsers() {
return userList;
}
@PostMapping
@ApiOperation(value = "添加用户", notes = "此接口用于添加新用户")
public User addUser(@ApiParam(value = "用户信息", required = true) @RequestBody User user) {
userList.add(user);
return user;
}
}
在上面的代码中，我们使用了 Swagger 的注解来标注 API 接口，使其在生成的文档中更具可读性。
4.4 访问文档
启动 Spring Boot 应用后，访问 http://localhost:8080/doc.html 便可以看到生成的 API 文档。你会发现所有的接口信息都呈现在一个漂亮的界面上，便于阅读和调用。
5. 小结
Knife4j 是一个非常强大的工具，能够帮助 Java 开发者快速生成并维护 RESTful API 的文档。通过简单的配置与注解，你可以轻松地将 API 文档化，从而提高团队的协作效率和项目的可维护性。希望本文能够帮助你快速入门 Knife4j，使你的 API 开发之旅更加顺畅！
