knife4j引入knife4j注解案例knife4j增强功能接口添加作者资源屏蔽访问页面加权控制接口排序分组排序请求参数缓存过滤请求参数禁用调试禁用搜索框SpringBoot

整合knife4j

在配置文件application.properties中开启增强模式

添加依赖

dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-boot-starter/artifactIdversion3.0.3/version

/dependency创建

org.springframework.beans.factory.annotation.Value;

import

org.springframework.context.annotation.Bean;

import

org.springframework.context.annotation.Configuration;

import

org.springframework.context.annotation.Import;

import

springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;

import

springfox.documentation.builders.*;

import

springfox.documentation.service.*;

import

springfox.documentation.spi.DocumentationType;

import

springfox.documentation.spring.web.plugins.Docket;

import

springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;Slf4j

Configuration

Import(BeanValidatorPluginsConfiguration.class)

public

{Value(${spring.application.name})private

String

Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(applicationName).select()//

添加Api注解才显示.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//

这里指定Controller扫描包路径

.apis(RequestHandlerSelectors.basePackage(com.yolo)).paths(PathSelectors.any()).build();}/***

ApiInfo

ApiInfoBuilder().title(API文档).description(API文档).contact(new

Contact(yolo,https://gitee.com/huanglei1111,2936412130qq.com)).version(1.0.0).build();}

}application.yml配置文件

https://doc.xiaominfo.com/knife4j

knife4j:#

true:关闭swaggerfalse:开启swaggerproduction:

falsebasic:#

tags表示该类的标签在页面会独立显示一个菜单ApiOperation(value

“保存用户”,

表示标签在页面会独立显示一个菜单ApiImplicitParam(name

“id”,

方法只有一个基本类型参数时加在方法上。

方法有多个参数时加在ApiImplicitParams内

name

默认值这个还是有必要填写的在页面进行请求时会自动填充ApiImplicitParams(value

{})

当请求方法中的请求参数很多的时候例如saveUser(String

username,

与ApiImplicitParam使用的效果等同根据个人喜好进行使用ApiModel(value

“用户信息”)

则需要加在UserDTO这个类上面(可以参照下面的示例)ApiModelProperty(value

“用户ID”,

属性的示例值在页面会自动填充该值ApiIgnore注解类、参数、方法注解后将不在Swagger

UI中显示案例

com.yolo.knife4j.controller;import

cn.hutool.core.collection.ListUtil;

import

com.yolo.knife4j.base.ResultVo;

import

com.yolo.knife4j.dto.UserAddRequest;

import

org.springframework.web.bind.annotation.*;import

import

java.util.Date;ApiResponses(value

{ApiResponse(code

ResultVo.builder().build().setCode(200).setSuccess(true).setTime(new

Date()).setMsg(保存用户成功).setData(userAddRequest);}ApiOperation(value

保存用户2,

ResultVo.builder().build().setCode(200).setSuccess(true).setTime(new

Date()).setMsg(保存用户成功).setData(userAddRequest);}GetMapping(/list)ApiOperation(value

查找用户列表,

StudentVO.builder().build().setAddress(wuhan).setCode(2);vo.setStudentVOS(ListUtil.of(studentVO));return

ResultVo.builder().build().setCode(200).setSuccess(true).setTime(new

Date()).setMsg(查找用户列表).setData(vo);}DeleteMapping(/{id})ApiOperation(value

删除用户,

ResultVo.builder().build().setCode(200).setSuccess(true).setTime(new

}响应参数

com.fasterxml.jackson.annotation.JsonFormat;

import

io.swagger.annotations.ApiModel;

import

io.swagger.annotations.ApiModelProperty;

import

lombok.experimental.Accessors;import

import

-8054007511410819665L;ApiModelProperty(value

响应状态码,

是否成功标识.true表示成功,false表示失败ApiModelProperty(success标识,true表示成功,false表示失败)private

boolean

操作成功时需要响应给客户端的响应数据ApiModelProperty(响应信息)private

String

msg;ApiModelProperty(响应数据)private

data;ApiModelProperty(当前时间)JsonFormat(pattern

yyyy-MM-dd

classpath:sign/*setting:language:

实体类列表enableVersion:

falseenableReloadCacheParameter:

trueenableFilterMultipartApiMethodType:

trueenableHost:

192.168.0.193:8000enableHomeCustom:

classpath:markdown/home.mdenableSearch:

falseenableFooter:

2019-[浙江八一菜刀股份有限公司](https://gitee.com/xiaoym/knife4j)enableDynamicParameter:

falseenableDebug:

如果在方法上使用了注解并且也在类上使用了注解那么最后的展示结果以方法上的注解为准

资源屏蔽

true:关闭swaggerfalse:开启swaggerproduction:

true然后重启项目

针对Swagger的资源接口,Knife4j提供了简单的Basic认证功能

简单点说指定一个用户名和密码访问

true:关闭swaggerfalse:开启swaggerproduction:

falsebasic:#

123456如果开启生产环境屏蔽了开启basic认证是不生效的

接口排序

这三个注解是存在优先级的也就是说当同时使用时只会有一个注解生效所以在使用的时候需要特别注意。

优先级规则如下

ApiSupport

我们在调试接口的时候有的接口会有很多参数当我们好不容易填好了所有的参数由于我们不小心关闭了页面下次再调试的时候发现还需要再次将参数输入一遍心态会爆炸吧所以

knife4j

我们在开发过程中经常会遇到这样的一个问题新增和修改接口修改接口需要传递修改的记录id但是新增则不需要而后端往往会将修改和新增的入参对象设置为一个对象那么这个对象中必然会存在

字段这就会对新增造成误导

支持了请求参数的过滤忽略实现方式也是非常的简单使用自定义增强注解ApiOperationSupport中的ignoreParameters属性,可以强制忽略要显示的参数

我们先看表单格式

username;ApiModelProperty(value

性别,example

province;ApiModelProperty(value

市)private

district;ApiModelProperty(value

详细地址)private

/saveUser)ApiOperation(新增用户信息-表单)ApiOperationSupport(author

String

userDTO){System.out.println(前端传递的用户信息

userDTO);return

/updateUser)ApiOperation(编辑用户信息)ApiOperationSupport(author

yolo)public

userDTO){System.out.println(前端传递的用户信息

userDTO);return

success;}在过滤字段的时候第一层我们只要填写对象中的属性名即可但如果需要过滤第二层根据忽略规则中的第二条我们在

UserDTO

专业说法是实例名.属性名以新增用户为例我们需要过滤用户id那么写法就是userDTO.id其中

userDTO

/saveUser)ApiOperation(新增用户信息)ApiOperationSupport(author

{userDTO.id,userDTO.userAddressDTO.id})public

String

userDTO){System.out.println(前端传递的用户信息

userDTO);return

falseenableDebug:该属性是一个Boolean值代表是否启用调试功能,默认值为true(代表开启调试)如果要禁用调试该值设为false

同样此操作也需要开发者在创建Docket逻辑分组对象时通过Knife4j提供的工具对象OpenApiExtensionResolver将扩展属性进行赋值

禁用搜索框

发者如果想要禁用Ui界面中的搜索功能需要通过增强属性进行配置此功能需要开启增强功能

knife4j:enable:

falseenableSearch:该属性是一个Boolean值代表是否启用搜索功能,默认值为true(代表开启搜索)如果要禁用搜索该值设为false

同样此操作也需要开发者在创建Docket逻辑分组对象时通过Knife4j提供的工具对象OpenApiExtensionResolver将扩展属性进行赋值。

具体的代码实现请参考禁用调试和自定义主页内容我这里就不重复了。