原文网址：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

依赖及配置

依赖

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

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

版本的区别如下：

版本	说明
1.9.6	蓝色皮肤风格,开始更名，增加更多后端模块
2.0~2.0.5	Ui重写，底层依赖的springfox框架版本是2.9.2
2.0.6~	底层springfox框架版本升级至2.10.5，OpenAPI规范是v2
3.0~	底层依赖springfox框架版本升级至3.0.3，OpenAPI规范是v3

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<UserVO> 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博客

Knife4j系列--使用/教程/实例/配置相关推荐

Swagger--使用/教程/实例/配置
原文网址:Swagger--使用/教程/实例/配置_IT利刃出鞘的博客-CSDN博客简介说明本文用实例介绍Swagger的使用. Swagger是很常用的接口文档工具,在类和方法 ...
大疆 DJI mobile SDK系列详细教程——运行实例代码（跑通大疆官方提供Mobile SDK里的sample code）
大疆 DJI mobile SDK系列详细教程--运行实例代码(跑通大疆官方提供Mobile SDK里的sample code) 文章目录一.官方文献与资源地址二.操作步骤提示:昨天在尝试跑通大 ...
Cisco 2950 系列交换机实例配置
Cisco Catalyst 2950系列智能以太网交换机,提供卓越的性能.易使用性以及集成的Cisco IOS软件.它通过DSCP.WRR等保证先进的服务质量.同时,它具有限速(Rate-limit ...
Oracle11g安装教程、配置实例、监听、客户端程序详解_Windows篇
Oracle11g安装教程.配置实例.监听.客户端程序详解_Windows篇文章目录 Oracle11g安装教程.配置实例.监听.客户端程序详解_Windows篇前言一.数据库的安装前准备,前提 ...
QCC304x系列开发教程（实战篇）之4.2QCC3040之MDE按键导入配置
查看全部教程开发请点击:高通蓝牙耳机QCC304x开发详解汇总(持续更新中) 查看本文全部文章请点击:QCC304x系列开发教程(实战篇)之4.2QCC3040之MDE按键导入配置 ========= ...
C# 读取西门子S7系列PLC教程及源码
创建 PLC 实例,连接和断开连接若要创建驱动程序的实例,需要使用此构造函数: public Plc(CpuType cpu, string ip, Int16 rack, Int16 slot) ...
Docker在Linux上运行NetCore系列（一）配置运行DotNetCore控制台
Docker在Linux上运行NetCore系列(一)配置运行DotNetCore控制台原文:Docker在Linux上运行NetCore系列(一)配置运行DotNetCore控制台转发请注明此文 ...
java 配置信息_[Java教程]java 配置信息类 Properties 的简单使用
[Java教程]java 配置信息类 Properties 的简单使用 0 2016-12-08 09:00:09 Properties :(配置信息类) 是一个表示持久性的集合 ,继承 Hashta ...
nginx系列之三：日志配置
** 前言 ** nginx系列之一:nginx入门 nginx系列之二:配置文件解读 nginx系列之三:日志配置 nginx系列之四:web服务器 nginx系列之五: 负载均衡 nginx系列之 ...

Knife4j系列--使用/教程/实例/配置

简介

实例