前言
API 文档对接是前后端分离时代必不可少的一个环节，为了极大的提升效率，一个简洁、易用且美观的文档至关重要。最初，API 文档是一个纯手工编写的 Word。但是，程序猿是一群极具追求自动化高效率的人。于是，随着代码而启动的全自动化在线文档诞生了，其中最具代表性的当属 swagger。swagger 虽高效，但也有不足。knife4j 对 swagger 进行了封装，弥补了其中的不足，包括但不限于参数忽略，离线（ md、html、doc、json ）文档等等。可以说是满足并超出了一个 API 文档应有的自我修养。
关于 knife4j
knife4j 官网：
有两个大版本 3.X 和 2.X ，官方解释如下
目前最新的版本是 3.0.2。
界面赏析
动手实践
示例版本
| 工具 | 版本 | |
|---|---|---|
| SpringBoot | 2.3.0.RELEASE | |
| knife4j | 3.0.2 |
1、引入依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
2、swagger 配置类（ knife4j 底层是 springfox）
如果你用过或正在使用 swagger 作为你的 API 文档，对这些代码应该不会陌生，因为它们并没有任何分别。
@Configuration
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
// 控制层包名，会自动扫描包里的所有接口
.apis(RequestHandlerSelectors.basePackage("org.programlife2016.knife4j.web"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
// 展示在主页的信息
return new ApiInfoBuilder()
// 文档标题
.title("knife4j")
// 文档描述
.description("knife4j示例文档")
// 你的联系方式
.contact(new Contact("ProgramLife2016", "xxx", "xxx"))
// 文档版本
.version("1.0")
.build();
}
}
3、实体类
@Getter
@Setter
@ToString
public class UserModel {
@ApiModelProperty("主键")
private Integer id;
@ApiModelProperty("名称")
private String name;
@ApiModelProperty("年龄")
private Integer age;
}
可以看到这里使用 @ApiModelProperty 注解替代了传统的 Java 注释，knife4j 会读取注解的值来作为参数的说明展示在文档上，对接者就可以清晰明了字段代表的属性。
4、控制层
@Api(tags = "用户模块")
@RestController
@RequestMapping("/user")
public class UserController {
@Autowired
private UserService userService;
@ApiOperation("添加")
@PostMapping("/add")
public CommonResult<UserModel> add(@RequestBody UserModel userModel) {
userService.add(userModel);
return CommonResult.success();
}
@ApiOperation("更新")
@PutMapping("/update")
public CommonResult<UserModel> update(@RequestBody UserModel userModel) {
userService.update(userModel);
return CommonResult.success();
}
}
这里使用到了两个注解 @Api 和 @ApiOperation。
@Api 是对整个类的说明，
@ApiOperation 是对单个接口的说明。
访问 knife4j 查看与调试接口
启动 SpringBoot 服务后浏览器访问 knife4j 就能看到‘界面赏析’中的效果图，地址为
knife4j 常用特性
knife4j 在 swagger 的基础上做了许多增强，这里介绍几个最常用的。
使用增强特性需在 application.yml 中开启
knife4j:
enable: true
过滤请求参数
在增改接口中，有时我们为了方便（其实就是懒），会用同一个 model，但在新增接口中是不需要传递id的，修改接口中又是必传的，在 API 文档新增接口如果展示了这个字段就会莫名其妙，这时，过滤请求参数就显得尤为重要。在 knife4j 中，只需一个 @ApiOperationSupport 注解即可搞定。
@ApiOperation("添加")
@ApiOperationSupport(ignoreParameters = {"id"})
@PostMapping("/add")
public CommonResult<UserModel> add(@RequestBody UserModel userModel) {
userService.add(userModel);
return CommonResult.success();
}
全局参数
前后端分离开发中一般使用 token 作为请求参数进行身份与权限鉴定，有放在 query（表单）和 header（请求头）的，knife4j 对这两种都进行了支持，只需在侧边栏‘文档管理 -> 全局参数设置’中设置。
离线文档
有时我们需要一份离线文档可以随时随地进行查看，knife4j 支持导出四种格式（ md、html、doc 、json）的离线文档，在侧边栏‘文档管理 -> 离线文档’中导出。
md 文档导出效果图
knife4j 对微服务架构的支持
如今，在互联网大厂的推动下，微服务架构越来越流行，knife4j 也实现了对微服务架构的支持。限于文章篇幅，官方文档也写得很详细，这里就止步于此，不再赘述，有需要的朋友请移步官方文档
