👋 热爱编程的小伙伴们，欢迎来到我的编程技术分享公众号！在这里，我会分享编程技巧、实战经验、技术干货，还有各种有趣的编程话题！
一、引言：跟接口文档说拜拜 👋
作为一名 Java 开发者，你是否还在为编写繁琐的 API 文档而头疼？传统的手动编写方式不仅耗时费力，而且容易出错，难以维护。今天，我们就来介绍一款神器 Knife4j，它可以帮助你轻松生成美观、易于使用的 API 文档，让你告别文档编写烦恼！
二、Knife4j 简介：API 文档界的“后起之秀”
简单来说，Knife4j 是一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案，它不仅拥有 Swagger 的所有功能，还做了很多优化和增强，例如：
界面更美观： 提供简洁美观的界面，方便用户浏览和使用 API 文档。 功能更丰富： 支持接口排序、搜索、分组等功能，支持多种格式输出。 易用性更高： 提供了更友好的配置方式，使用起来更加简单方便。
三、Spring Boot 集成 Knife4j：三步搞定，轻松上手 🚀
1. 添加依赖：引入 Knife4j 包
在你的 Spring Boot 项目的 pom.xml
文件中添加以下依赖：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>
2. 配置 Knife4j：告诉它你的 API 信息
创建一个配置类，例如 Knife4jConfiguration，使用 @EnableSwagger2WebMvc
注解开启 Swagger 功能，并配置 Docket Bean，就像这样：
package com.muqing.common.config;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
@Configuration
@EnableSwagger2WebMvc
publicclass Knife4jConfiguration {
@Bean(value = "mq-admin-api")
public Docket defaultApi2() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.title("MQ-ADMIN API文档")
.description("# 基于 Spring Boot 与 Vue3 的后台管理系统。")
.termsOfServiceUrl("https://doc.uyii.cn/")
.contact("zhy@uyii.cn")
.version("1.0")
.build())
.select()
.paths(PathSelectors.any())
.build();
return docket;
}
}
3. 运行项目：见证奇迹的时刻 ✨
启动你的 Spring Boot 应用，在浏览器中访问 http://localhost:8800/doc.html
，你就能看到 Knife4j 生成的 API 文档啦！
四、进阶用法：玩转 Knife4j，定制你的 API 文档 🎨
分组管理 API 文档：
@Bean
public Docket adminApi() {
returnnew Docket(DocumentationType.SWAGGER_2)
.groupName("admin")
.select()
.apis(RequestHandlerSelectors.basePackage("com.muqing.admin")) // 修改为你的模块包路径
.paths(PathSelectors.any())
.build();
}
@Bean
public Docket frontApi() {
returnnew Docket(DocumentationType.SWAGGER_2)
.groupName("front")
.select()
.apis(RequestHandlerSelectors.basePackage("com.muqing.front")) // 修改为你的模块包路径
.paths(PathSelectors.any())
.build();
}
自定义 API 信息：
@RestController
@RequestMapping("/users")
@Api(tags = "用户管理")
public class UserController {
@GetMapping("/{id}")
@ApiOperation("获取用户信息")
public User getUser(@PathVariable Long id) {
// ...
}
}
五、实战演练：小试牛刀，巩固学习成果 💪
我们来创建一个简单的 Spring Boot 项目，演示如何使用 Knife4j 生成 API 文档：
1. 创建一个 Spring Boot 项目，添加 Web 依赖和 Knife4j 依赖。
2. 创建一个 FrontIndexController
，编写接口：
package com.muqing.front.controller;
import com.muqing.common.api.ApiResult;
import com.muqing.front.entity.Article;
import com.muqing.front.service.FrontIndexService;
import com.muqing.front.vo.IndexVo;
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* IndexController
*
* @author zhy
* @since 2023/6/5
*/
@RestController
@Api(tags = "后台首页")
@RequestMapping("/front")
publicclass FrontIndexController {
@Autowired
private FrontIndexService frontIndexService;
/**
* 首页博主信息
*
* @return {@link ApiResult}<{@link IndexVo}>
*/
@ApiOperation("博主信息")
@GetMapping()
public ApiResult<IndexVo> index() {
IndexVo IndexVo = frontIndexService.getAuthorInfo();
return ApiResult.success(IndexVo);
}
/**
* 关于我
*
* @return {@link Article}
*/
@ApiOperation("关于我")
@GetMapping("/about")
public ApiResult<Article> about() {
Article article = frontIndexService.getAbout();
return ApiResult.success(article);
}
}
3. 运行项目，访问 http://localhost:8080/doc.html
，查看生成的 API 文档。
结语：API 文档，从此轻松搞定 🎉
Knife4j 为我们提供了一种简单高效的方式来生成和管理 API 文档，从此告别繁琐的手动编写，让前后端协作更加顺畅！ 希望这篇文章能够帮助你快速上手 Knife4j，更多进阶的技能请阅读官方文档！ 🎉
个人观点，仅供参考，非常感谢各位朋友们的支持与关注！
如果你觉得这个作品对你有帮助，请不吝点赞、在看，分享给身边更多的朋友。如果你有任何疑问或建议，欢迎在评论区留言交流。
