文章目录

一、Knife4j
二、环境准备
- 1.引入依赖
- 2.添加配置
- 3.设置配置类
- 4.运行访问
三、基本用法
- 1.控制器
- 2.封装类
四、效果演示
五、其它
- 1. 生成本地API文件
- 2. 全局参数设置

一、Knife4j

Knife4j是国人开发的一个基于Swagger2的在线文档框架, 可以说是Swagger的升级版的API文档框架, 它可以扫描控制器所在的包, 并解析每一个控制器及其内部的处理请求的方法, 生成在线API文档, 为前后端的开发人员的沟通提供便利

二、环境准备

1.引入依赖

创建SpringBoot项目, 勾选Spring web框架 , 并在pom.xml中添加依赖：

<!-- Knife4j在线API文档的依赖 -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.9</version>
</dependency>
<!-- lombok依赖包, 用于简化代码 -->
<dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional>
</dependency>

2.添加配置

引入依赖后, 在application.properties中添加配置：

#启用knife4j增强模式
knife4j.enable=true
#生产模式屏蔽, true将禁止访问API在线文档, false可以看到文档, 密码失效
knife4j.production=false
#Basic认证功能，即是否需要通过用户名、密码验证后才可以访问在线API文档
knife4j.basic.enable=true
#如果开启Basic认证却未配置用户名与密码，默认是：admin/123321, 即使输入对了, 也会一直循环
knife4j.basic.username=root
knife4j.basic.password=root
#为了节省流量, 返回数据时, 配置不返回属性值为null的数据
spring.jackson.default-property-inclusion=non_null

3.设置配置类

以上两步完成后, 在项目配置包下创建Knife4jConfiguration.class类

package cn.qingtian.knife4j.config;import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import org.springframework.beans.factory.annotation.Autowired;
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.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;/*** Knife4j（Swagger2）的配置*/
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {/*** 【重要】指定Controller包路径*/private String basePackage = "cn.qingtian.knife4j.controller";/*** 分组名称*/private String groupName = "base-knife4j";/*** 主机名*/private String host = "http://java.qingtian.cn";/*** 标题*/private String title = "API在线文档工具";/*** 简介*/private String description = "Knife4j演示";/*** 服务条款URL*/private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";/*** 联系人*/private String contactName = "项目研发部";/*** 联系网址*/private String contactUrl = "http://java.qingtian.cn";/*** 联系邮箱*/private String contactEmail = "java@qingtian.cn";/*** 版本号*/private String version = "1.0.0";@Autowiredprivate OpenApiExtensionResolver openApiExtensionResolver;@Beanpublic Docket docket() {String groupName = "1.0.0";Docket docket = new Docket(DocumentationType.SWAGGER_2).host(host).apiInfo(apiInfo()).groupName(groupName).select().apis(RequestHandlerSelectors.basePackage(basePackage)).paths(PathSelectors.any()).build().extensions(openApiExtensionResolver.buildExtensions(groupName));return docket;}private ApiInfo apiInfo() {return new ApiInfoBuilder().title(title).description(description).termsOfServiceUrl(termsOfServiceUrl).contact(new Contact(contactName, contactUrl, contactEmail)).version(version).build();}}

4.运行访问

前三步完成后, 启动此项目, 在浏览器上访问http://localhost:8080/doc.html, 输入账号密码= root/root

三、基本用法

1.控制器

Api : 添加在控制类上, 通过tags属性, 可以指定此控制器的名称, 还可以在tags上添加序号, 控制各控制器之间的排序, 如"1. 管理员模块" "2. 评论模块" Knife4j框架会自动进行排序
@ApiOperation : 添加在控制器类中的处理方法上, 用于配置方法在API文档中的名称, 如@ApiOperation("增加管理员")
@ApiOperationSupport : 添加在控制器类的处理方法上, 通过属性order, 可配置在本控制器上此方法的显示排序, 建议增(order=10), 删(order=20), 改(order=30), 查(order=40)
@ApiImplicitParam : 添加在控制器类的处理方法上, 可以配置此方法参数在API文档中的显示, 属性name方法名 value方法描述 required是否必须 dataType参数类型 example参数示例
@ApiImplicitParams : 添加在控制器类的处理方法上, 与@ApiImplicitParam配合使用, 用于有多个参数的方法, 如@ApiImplicitParams(@ApiImplParam(参数1配置), @ApiImplParam(参数2配置))

2.封装类

@ApiModel : 添加在封装类上, 用于配置封装类在API文档中的名称, 如@ApiModel("用户数据")
@ApiModelProperty : 添加在封装类中的属性上, 用于配置封装类在API文档中的显示, 常用属性value属性名称 required是否必须 exampl参数实例 dataType参数类型

在自定义的封装类中, 必须有GET和SET方法, 不然会出现 406-文件不可被接收错误

四、效果演示

在cn.qingtian.knife4j下创建包pojo, 在pojo下创建dto和vo并创建以下类

package cn.qingtian.knife4j.pojo.dto;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;import java.io.Serializable;@Data
@ApiModel("用户DTO")
public class UserDTO implements Serializable {@ApiModelProperty(value = "用户账号",example = "java1234567", required = true)private String username;@ApiModelProperty(value = "用户密码",example = "12345678", required = true)private String password;
}

package cn.qingtian.knife4j.pojo.vo;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;import java.io.Serializable;@Data
@ApiModel("用户VO")
public class UserVO implements Serializable {@ApiModelProperty(name = "username",value = "用户账号",example = "java1234567")private String username;@ApiModelProperty(name = "password",value = "用户密码",example = "12345678")private String password;
}

在cn.qingtian.knife4j下创建包response, 并创建以下类

package cn.qingtian.knife4j.response;/*** 枚举类, 定义本项目的业务返回码*/
public enum ResponseCode {OK(200),BAD_REQUEST(400),UNAUTHORIZED(401),FORBIDDEN(403),NOT_FOUND(404),NOT_ACCEPTABLE(406),CONFLICT(409),INTERNAL_SERVER_ERROR(500);private Integer value;ResponseCode(Integer value) {this.value = value;}public Integer getValue(){return value;}
}

package cn.qingtian.knife4j.response;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;import java.io.Serializable;@Data
@ApiModel("通用业务响应数据")
public class JsonResult<T> implements Serializable {// 业务返回码@ApiModelProperty(name = "state",value = "业务返回码",example = "401 402 403", position = 1)private Integer state;// 业务消息@ApiModelProperty(name = "message",value = "业务消息",example = "请求参数格式错误, 密码错误",position = 2)private String message;// 业务数据@ApiModelProperty(name = "data",value = "业务数据",example = "3")private T data;// 构造方法私有化, 限制此类创建规则private JsonResult(){}// 处理成功返回结果public static <T> JsonResult<T> ok(T data){JsonResult<T> jsonResult = new JsonResult<>();jsonResult.state = ResponseCode.OK.getValue();jsonResult.data = data;return jsonResult;}public static JsonResult<Void> ok(String message){JsonResult<Void> jsonResult = new JsonResult<>();jsonResult.state = ResponseCode.OK.getValue();jsonResult.message = message;return jsonResult;}// 处理成功返回结果, 没有返回消息和返回数据public static JsonResult<Void> ok(){return ok(null);}// 处理失败返回的结果, 返回结果一般有错误信息和业务返回码, 不包含处理数据结果public static JsonResult<Void> fail(ResponseCode state, String message){JsonResult<Void> jsonResult = new JsonResult<>();jsonResult.state = state.getValue();jsonResult.message = message;return jsonResult;}
}

在cn.qingtian.knife4j下创建包controller, 并创建以下类

package cn.qingtian.knife4j.controller;import cn.qingtian.knife4j.pojo.dto.UserDTO;
import cn.qingtian.knife4j.pojo.vo.UserVO;
import cn.qingtian.knife4j.response.JsonResult;
import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;import java.util.ArrayList;
import java.util.List;@RestController
@RequestMapping("/user")
@Api(tags = "1. 用户管理模块")
public class UserController {@ApiOperation(value = "增加用户")@ApiOperationSupport(order = 10)@PostMapping("/add-new")public UserVO addNew(UserDTO userDTO){UserVO userVO = new UserVO();userVO.setUsername("root");userVO.setPassword("root");return userVO;}@ApiOperation(value = "删除用户")@ApiOperationSupport(order = 20)@ApiImplicitParam(name = "userId",value = "用户id",required = true,dataType = "long",example = "1")@DeleteMapping("/delete/{userId}")public JsonResult delete(@PathVariable Long userId){return JsonResult.ok();}@ApiOperation(value = "修改用户")@ApiOperationSupport(order = 30)@ApiImplicitParams(@ApiImplicitParam(name = "userId",value = "用户id",required = true,dataType = "long",example = "1"))@PutMapping("/update/{userId}")public JsonResult update(@PathVariable Long userId, UserDTO userDTO){return JsonResult.ok();}@ApiOperation(value = "查询用户列表")@ApiOperationSupport(order = 40)@GetMapping("/list")public JsonResult list(){List<UserVO> list = new ArrayList<>();UserVO userVO = new UserVO();userVO.setUsername("root");userVO.setPassword("root");list.add(userVO);return JsonResult.ok(list);}
}

启动项目,效果:

1. 增加用户

2. 删除用户

3. 修改用户

4. 查询用户列表

五、其它

1. 生成本地API文件

在线API文档导出到本地

2. 全局参数设置

通过全局参数设置可以, 可以设置cookie等, 调试发送请求时, 会携带此请求头

SpringBoot整合Knife4j框架相关推荐

SpringBoot整合knife4j
SpringBoot整合knife4j 导入依赖  <dependencies><dependency><groupI ...
SpringBoot整合CXF框架开发
在开发过程中遇到了一些使用webservice开发的需求,后查阅资料学习,可上手开发.在学习过程中实现了个小demo,为了养成良好的总结习惯(我还没这"坏习惯"),特意写了个小呆萌 ...
SpringBoot整合knife4j ，神仙朋友介绍的
SpringBoot 整合 knife4j " knife4j 官方文档地址 https://doc.xiaominfo.com/knife4j/ " 之前经常使用 swagger ...
SpringBoot整合Web框架
SpringBoot整合Web框架 Spring Boot可以轻松创建独立的.基于Spring的生产级应用程序它可以让你"运行即可". 大多数Spring Boot应用程序只需要 ...
详解SpringBoot整合Mybatis框架
文章目录前言一.创建SpringBoot项目二.配置Mybatis 1. 在pom.xml文件中添加jar包依赖 2. SpringBoot整合Mybatis配置文件三.创建Mapper接口 ...
2023新版图文详解SpringBoot整合SSM框架(附源码)
版权声明本文原创作者:谷哥的小弟作者博客地址:http://blog.csdn.net/lfdfhl 教程概述本教程以图文形式详细讲解SpringBoot整合SSM框架的流程以及具体步骤及其注意 ...
idea中springboot整合Axis2框架一
idea中springboot整合Axis2框架一 1.Axis2框架所需要的maven坐标: 2.编写webservice服务类 3.在WEB-INF/services/webService/MET ...
SpringBoot整合Knife4j问题
1. 前言最近工作中需要到Knife4j, 加上自己的项目充电鸭上本来好的Knife4j文档突然不好使了,遇到的问题正好记录一下 2.个人网站遇到的问题个人网站本来的事还挺好用的,经过我得一阵折腾 ...
SpringBoot 整合 knife4j
文章目录简述 2. 导入依赖 3. 创建配置类 4. 创建User实体类 5. 创建开发接口 6. 启动项目简述 Swagger是一款测试文档Api接口,具体用法见SpringBoot整合Swag ...

SpringBoot整合Knife4j框架