原文网址：Knife4j系列--使用/教程/实例/配置_IT利刃出鞘的博客-CSDN博客

简介

说明

本文用示例介绍knife4j的用法。（SpringBoot整合knife4j）

Knife4j是一个很好用的接口文档工具。之前用过Swagger，觉得页面不太好，浏览技术网站时，偶然发现swagger-bootstrap-ui，它能将接口进行归类。

早期，swagger-boostrap-ui是1.x版本，如今swagger-bootsrap-ui到2.x，同时也更改名字Knife4j，适用于单体和微服务项目。

Knife4j跟Swagger用法基本一样，swagger用法见：Swagger--使用/教程/实例/配置_IT利刃出鞘的博客-CSDN博客

官网

首页：knife4j
文档：knife4j
gitee地址：https://gitee.com/xiaoym/knife4j

技术星球

我建立了一个IT技术星球，网站是：learn.skyofit.com（自学精灵）。内容有：Java真实面试题、Java设计模式实战、Shiro项目实战、Idea和Navicat的“魔法”教程、SpringBoot进阶、架构与微服务设计、高并发实战、Java入门实战、网站防御技术、JavaWeb入门项目等。

网站的定位：系列文章、高质量、注重实战、贴近实际项目，适合如下人群：入门学Java的、想进阶为高级Java开发的、想进阶为Java架构师的、想跳槽的、想升职加薪的、想防御网站被黑客攻击的。欢迎加入~

实例

官网文档：1.6 快速开始 | knife4j

依赖及配置

依赖

com.github.xiaoyminknife4j-spring-boot-starter3.0.3

本处我使用比较新的版本展示。（目前2.0.9是最新的发布版，最稳定。）

版本的区别如下：

Knife4j配置（非必要）

配置方案：使用openApi3.0

默认引入包就可以直接用了（无需配置）。本处只是示例如果自定义一些东西该怎么写。

package com.example.demo.config;import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
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.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableOpenApi
// @EnableKnife4j
// @EnableSwagger2
public class Knife4jConfig {@Beanpublic Docket docket() {Docket docket = new Docket(DocumentationType.OAS_30).apiInfo(new ApiInfoBuilder().title("我的标题").description("我的描述")// .termsOfServiceUrl("http://www.xx.com/").contact(new Contact("knife", "https://knife.blog.csdn.net/", "xx@qq.com")).version("1.0").build())// 分组名称.groupName("all").select()// 这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.example.demo")).paths(PathSelectors.any()).build();return docket;}
}

其他配置方案：使用swagger2

package com.example.demo.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.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class Knife4jConfig {@Bean(value = "defaultApi2")public Docket defaultApi2() {Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder().title("我的标题").description("我的描述")// .termsOfServiceUrl("http://www.xx.com/").contact(new Contact("IT利刃出鞘", "https://knife.blog.csdn.net", "xx@qq.com")).version("1.0").build())//分组名称.groupName("all").select()//指定Controller扫描路径。可以不具体到controller，它会扫描指定路径下的所有.apis(RequestHandlerSelectors.basePackage("com.example.demo")).paths(PathSelectors.any()).build();return docket;}
}

代码

Controller

package com.example.demo.business.user.controller;import com.example.demo.business.user.request.UserAddRequest;
import com.example.demo.business.user.request.UserEditRequest;
import com.example.demo.business.user.request.UserQueryRequest;
import com.example.demo.business.user.vo.UserVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.BeanUtils;
import org.springframework.web.bind.annotation.*;import javax.validation.Valid;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;@Api(tags = "用户")
@RestController
@RequestMapping("/user")
public class UserController {@ApiOperation("添加")@PostMapping("/add")public UserVO add(@RequestBody @Valid UserAddRequest userAddRequest) {// 将数据写到数据库UserVO userVO = new UserVO();BeanUtils.copyProperties(userAddRequest, userVO);userVO.setId(1L);userVO.setCreateTime(LocalDateTime.now());userVO.setUpdateTime(LocalDateTime.now());return userVO;}@ApiOperation("修改")@PostMapping("/edit")public UserVO edit(@RequestBody @Valid UserEditRequest userEditRequest) {// 修改数据库的数据UserVO userVO = new UserVO();BeanUtils.copyProperties(userEditRequest, userVO);userVO.setUpdateTime(LocalDateTime.now());return userVO;}@ApiOperation("查找")@GetMapping("/find")public List find(UserQueryRequest userQueryRequest) {return new ArrayList<>();}@ApiOperation("删除")@PostMapping("/delete")public void delete(Long id) {// 将数据库数据删除}
}

Entity

说明

        本处我将增删改查都单独写一个实体类。

        当然，也可以将增删改的参数都写到一个实体里边，通过@Null，@NotNull以及它们的groups属性来指定属于哪个分组。这样写在运行时不会有问题，但在Knife4j页面显示时会不正常，原因是：Swagger没有很好地处理好这种情况。

添加

package com.example.demo.business.user.request;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;import javax.validation.constraints.NotBlank;@Data
@ApiModel("添加用户")
public class UserAddRequest {@ApiModelProperty(value = "用户名", required = true)@NotBlank(message = "用户名不能为空")private String userName;@ApiModelProperty("昵称")private String nickName;@ApiModelProperty("邮箱")private String email;
}

修改

package com.example.demo.business.user.request;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;@Data
@ApiModel("修改用户")
public class UserEditRequest {@ApiModelProperty(value = "用户ID", required = true)@NotNull(message = "用户ID不能为空")private Long id;@ApiModelProperty(value = "用户名", required = true)@NotBlank(message = "用户名不能为空")private String userName;@ApiModelProperty("昵称")private String nickName;@ApiModelProperty("邮箱")private String email;
}

查询

package com.example.demo.business.user.request;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.format.annotation.DateTimeFormat;import java.time.LocalDateTime;@Data
@ApiModel(value = "用户实体", description = "用户description")
public class UserQueryRequest {@ApiModelProperty("用户id")private Long id;@ApiModelProperty("用户名")private String userName;@ApiModelProperty("昵称")private String nickName;@ApiModelProperty("邮箱")private String email;@ApiModelProperty("创建时间")@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")private LocalDateTime createTime;@ApiModelProperty("修改时间")@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")private LocalDateTime updateTime;
}

VO

package com.example.demo.business.user.vo;import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;import java.time.LocalDateTime;@Data
@ApiModel(value = "用户实体", description = "用户description")
public class UserVO {@ApiModelProperty("用户id")private Long id;@ApiModelProperty("用户名")private String userName;@ApiModelProperty("昵称")private String nickName;@ApiModelProperty("邮箱")private String email;@ApiModelProperty(value = "创建时间")@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")private LocalDateTime createTime;@ApiModelProperty(value = "修改时间")@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")private LocalDateTime updateTime;@ApiModelProperty("删除标记。0：未删除 其他：已删除")private Long deletedFlag;
}

测试

knife4j跟Tomcat共用一个端口，默认Tomcat是8080。访问地址：

http://localhost:8080/doc.html

分组Url

“分组Url”是文档地址，其他软件（比如apifox）可以将它作为导入文档的url。

此网址可以直接访问：http://localhost:8080/v3/api-docs?group=all

文档

本处展示添加用户接口的文档：

自测

本处展示添加用户的自测方法

测试结果

问题解决

全局响应的处理

见：Knife4j--解决整合@ControllerAdvice时访问失败的问题_IT利刃出鞘的博客-CSDN博客

清缓存

见：Knife4j--清除缓存的方法_IT利刃出鞘的博客-CSDN博客

上传文件

见：Knife4j--解决不显示文件上传的问题_IT利刃出鞘的博客-CSDN博客

本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场，不承担相关法律责任。如若转载，请注明出处。 如若内容造成侵权/违法违规/事实不符，请点击【内容举报】进行投诉反馈！