springboot整合knife4j，从此告别⼿写接⼝⽂档

关于knife4j

Knife4j的前⾝是swagger-bootstrap-ui,前⾝swagger-bootstrap-ui是⼀个纯swagger-ui的ui⽪肤项⽬

⼀开始项⽬初衷是为了写⼀个增强版本的swagger的前端ui,但是随着项⽬的发展,⾯对越来越多的个性化需求,不得不编写后端Java代码以满

⾜新的需求,在swagger-bootstrap-ui的1.8.5~1.9.6版本之间,采⽤的是后端Java代码和Ui都混合在⼀个Jar包⾥⾯的⽅式提供给开发者使

⽤.这种⽅式虽说对于集成swagger来说很⽅便,只需要引⼊jar包即可,但是在微服务架构下显得有些臃肿。

因此,项⽬正式更名为knife4j,取名knife4j是希望她能像⼀把⼔⾸⼀样⼩巧,轻量,并且功能强悍,更名也是希望把她做成⼀个为Swagger接⼝⽂

档服务的通⽤性解决⽅案,不仅仅只是专注于前端Ui前端.

swagger-bootstrap-ui的所有特性都会集中在knife4j-spring-ui包中,并且后续也会满⾜开发者更多的个性化需求.

主要的变化是,项⽬的相关类包路径更换为4j前缀,开发者使⽤增强注解时需要替换包路径

后端Java代码和ui包分离为多个模块的jar包,以⾯对在⽬前微服务架构下,更加⽅便的使⽤增强⽂档注解(使⽤SpringCloud微服务项⽬,只需

要在⽹关层集成UI的jar包即可,因此分离前后端)

knife4j沿⽤swagger-bootstrap-ui的版本号,第1个版本从1.9.6开始,关于使⽤⽅法,请参考⽂档(摘⾃knife4j官⽅介绍)。

引⼊knife4j

knife4j主要的版本基本如下所⽰

版本说明

1.9.6蓝⾊⽪肤风格,开始更名，增加更多后端模块

2.0~2.0.5Ui重写，底层依赖的springfox框架版本是2.9.2

2.0.6~层springfox框架版本升级知2.10.5,OpenAPI规范是v2

3.0~底层依赖springfox框架版本升级⾄3.0.3,OpenAPI规范是v3

我们引⼊的是3.0.3，由于3.x只发布了⼀个版本，稳定性可能存在⼀定的问题，如果你想最求稳定，那么推荐你使⽤2.x，由于我这⾥只是

demo展⽰，加上我⾃⼰喜欢新版本，所以我这⾥使⽤了3.0.3，提前帮⼤家猜猜坑。

in

knife4j-spring-boot-starter

3.0.3

注意

knife4j已经引⼊了springfox，所以在使⽤的时候⽆需再次引⼊

springfox，否则有可能会导致版本冲突，如果你在⽹关聚合时，必须禁⽤knife4j的增强功能。

使⽤Knife4j2.0.6及以上的版本，SpringBoot的版本必须⼤于等于2.2.x

创建Swagger配置依赖

package;

importBean;

importConfiguration;

importApiInfoBuilder;

importPathSelectors;

importRequestHandlerSelectors;

importContact;

importDocumentationType;

importDocket;

importEnableSwagger2;

@Configuration

@EnableSwagger2

publicclassKnife4jConfiguration{

@Bean(value="defaultApi2")

publicDocketdefaultApi2(){

StringgroupName="3.X版本";

Docketdocket=newDocket(_30)

.apiInfo(newApiInfoBuilder()

.title("这是knife4jAPI")

.description("#这⾥记录服务端所有的接⼝的⼊参，出参等等信息")

.termsOfServiceUrl("")

.contact(newContact("逆流星","","361426201@"))

.version("3.0")

.build())

//分组名称

.groupName(groupName)

.lect()

//这⾥指定Controller扫描包路径

.apis(ckage("ller"))

.paths(())

.build();

returndocket;

}

}

这⾥需要注意⼀点，如果你使⽤的是2.x，那么需要将@EnableSwagger2替换成@EnableSwagger2WebMvc，因为

@EnableSwagger2是在3.x才引⼊的注解，并且将@EnableSwagger2WebMvc设置为不推荐使⽤。

配置项⽬名和端⼝信息

rver:

port:8818

spring:

application:

name:notes

创建⼀个简单的RESTful接⼝

package;

importApi;

importApiImplicitParam;

importApiOperation;

importGetMapping;

importRequestMapping;

importRequestParam;

importRestController;

@RestController

@RequestMapping(value="/test")

@Api(tags="测试swagger")

publicclassKnife4jTestController{

@GetMapping(value="/hello")

@ApiImplicitParam(name="name",value="姓名",required=true)

@ApiOperation("测试接⼝")

publicStringtest(@RequestParam("name")Stringname){

return"hello"+name+",Iammeimeihan";

}

}

启动项⽬

如果你在启动项⽬的时候抛出：Failedtostartbean‘documentationPluginsBootstrapper’;nestedexceptionis

interException

千万不要慌，那是因为你的springboot版本太⾼，应该是2.6.x，由于Springfox使⽤的路径匹配是基于AntPathMatcher，⽽Spring

Boot2.6.X使⽤的是PathPatternMatcher，所以将MVC的路径匹配规则改成AntPathMatcher，在配置⽂件中加⼊如下参数即可（如果

没有报错，可以跳过这个环节）

spring:

mvc:

pathmatch:

#Springfox使⽤的路径匹配是基于AntPathMatcher的，⽽SpringBoot2.6.X使⽤的是PathPatternMatcher

#所以需要配置此参数

matching-strategy:ant_path_matcher

到此为⽌，knife4j已经完美的运⾏起来了，后端⼈员在⾃测的时候再也不需要使⽤postman了，也不需要给前端单独写接⼝⽂档了，⼀

下⼦就增加的⾃⼰的摸鱼时间，美滋滋。

knife4j增强功能

什么是knife4j的增强功能？我们在前⾯看到的只是knife4j最基础的使⽤⽅式，knife4j还有很多强⼤的功能还没有展⽰出来，⽐如：

i18n国际化、接⼝添加作责、⾃定义⽂档、访问权限控制、接⼝排序、到处离线⽂档、过滤请求参数等等，这些都是knife4j的增强功能，

那如何开启knife4j的增强功能呢？

Knife4j⾃2.0.6版本开始,将⽬前在Ui界⾯中⼀些个性化配置剥离,开发者可以在后端进⾏配置，并且提供的knife4j-spring-boot-strater组

件⾃动装载，开发者可以在配置⽂件中决定需要开启的功能。

springboot中knife4j的完整参数如下：

knife4j:

enable:true

documents:

-

group:2.X版本

name:接⼝签名

locations:classpath:sign/*

tting:

language:zh-CN

enableSwaggerModels:true

enableDocumentManage:true

swaggerModelName:实体类列表

enableVersion:fal

enableReloadCacheParameter:fal

enableAfterScript:true

enableFilterMultipartApiMethodType:POST

enableFilterMultipartApis:fal

enableRequestCache:true

enableHost:fal

enableHostText:192.168.0.193:8000

enableHomeCustom:true

homeCustomLocation:classpath:markdown/

enableSearch:fal

enableFooter:fal

enableFooterCustom:true

footerCustomContent:ApacheLicen2.0|Copyright2019-[浙江⼋⼀菜⼑股份有限公司](/xiaoym/knife4j)

enableDynamicParameter:fal

enableDebug:true

enableOpenApi:fal

enableGroup:true

cors:fal

production:fal

basic:

enable:fal

urname:test

password:12313

knife4j的增强功能是需要开启的，默认关闭，开启也是⼗分的简单，在以前的版本中,开发者需要在配置⽂件中⼿动使⽤@EnableKnife4j

来使⽤增强，⾃2.0.6版本后,只需要在配置⽂件中配置=true即可不在使⽤注解

注意：要使⽤Knife4j提供的增强，=true必须开启。包括后⾯所讲解到的所有增强功能，都需要设置这个参数。

下⾯我来介绍以下上⾯的这些属性值所表达的是什么意思

属性默认值说明

fal是否开启Knife4j增强模式

l是否开启⼀个默认的跨域配置,该功能配合⾃定义Host使⽤

tionfal是否开启⽣产环境保护策略,详情参考⽂档

对Knife4j提供的资源提供BasicHttp校验,保护⽂档

fal关闭BasicHttp功能

mebasic⽤户名

rdbasic密码

nts⾃定义⽂档集合，该属性是数组

所属分组

类似于接⼝中的tag,对于⾃定义⽂档的分组

ons

markdown⽂件路径,可以是⼀个⽂件夹(classpath:markdowns/*)，也可以是单

个⽂件(classpath:md/)

g前端Ui的个性化配置属性

AfterScripttrue调试Tab是否显⽰AfterScript功能,默认开启

gezh-CNUi默认显⽰语⾔,⽬前主要有两种:中⽂(zh-CN)、英⽂(en-US)

SwaggerModelstrue是否显⽰界⾯中SwaggerModel功能

rModelName

Swagger

Models

重命名SwaggerModel名称,默认

DocumentManagetrue是否显⽰界⾯中"⽂档管理"功能

ReloadCacheParameterfal是否在每个Debug调试栏后显⽰刷新变量按钮,默认不显⽰

Versionfal是否开启界⾯中对某接⼝的版本控制,如果开启，后端变化后Ui界⾯会存在⼩蓝点

RequestCachetrue是否开启请求参数缓存

FilterMultipartApisfal

针对RequestMapping的接⼝请求类型,在不指定参数类型的情况下,如果不过滤,默

认会显⽰7个类型的接⼝地址参数,如果开启此配置,默认展⽰⼀个Post类型的接⼝地

址

FilterMultipartApiMethodTypePOST具体接⼝的过滤类型

Hostfal是否启⽤Host

HomeCustomfal是否开启⾃定义主页内容

stomLocation主页内容Markdown⽂件路径

Searchfal是否禁⽤Ui界⾯中的搜索框

Footertrue是否显⽰Footer

FooterCustomfal是否开启⾃定义Footer

CustomContentfal⾃定义Footer内容

DynamicParameterfal是否开启动态参数调试功能

Debugtrue启⽤调试

OpenApitrue显⽰OpenAPI规范

Grouptrue显⽰服务分组

属性默认值说明

接⼝添加作者

前端李雷在对接接⼝的时候发现接⼝有问题，但是不知道是谁在负责这个接⼝，通过层层查找，终于找到了是韩梅梅负责，这样⼤⼤的阻碍

了开发的效率，所以这个时候在接⼝上标记对应的开发着，能让找⼈和背锅都能做到⾮常精准。

使⽤⽅式：添加注解@ApiOperationSupport(author=“逆流星007”)

@GetMapping(value="/hello")

@ApiImplicitParam(name="name",value="姓名",required=true)

@ApiOperation("测试接⼝")

@ApiOperationSupport(author="逆流星007")

publicStringtest(@RequestParam("name")Stringname){

return"hello"+name+",Iammeimeihan";

}

但是对于后端来说，在每个接⼝上都加上这个注解，着实有点浪费时间了，所以knife4j在收到反馈之后，决定在Controller类上增加⼀

个注解，表⽰当前接⼝类下的所有接⼝都是该作者负责开发。

因此在2.0.3版本中新增加了@ApiSupport注解,该注解⽬前有两个属性,分别是author(作者)和order(排序)

注意：如果在controller类上添加了@ApiSuppor注解，并且在某个接⼝上也添加了@ApiOperationSupport注解，那么接⼝上的作者

将会覆盖controller类上的作者

@RestController

@RequestMapping(value="/test")

@ApiSupport(author="逆流星007-controller")

@Api(tags="测试swagger")

publicclassKnife4jTestController

@RestController

@RequestMapping(value="/test")

@ApiSupport(author="逆流星007-controller")

@Api(tags="测试swagger")

publicclassKnife4jTestController{

@GetMapping(value="/hello")

@ApiImplicitParam(name="name",value="姓名",required=true)

@ApiOperation("测试接⼝")

@ApiOperationSupport(author="逆流星逆流星007-test")

publicStringtest(@RequestParam("name")Stringname){

return"hello"+name+",Iammeimeihan";

}

}

访问权限控制

虽然knife4j给我们提供了很⽅便的在线接⼝⽂档，俗话说的好，凡事都具有两⾯性，有利⾃然也有弊，那就是在⽣茶环境上，也会显⽰出

接⼝⽂档，这是⾮常危险的⼀件事情，问题如下：

系统部署⽣产环境时,我们想屏蔽Swagger的⽂档功能,不管是接⼝或者html⽂档

通常我们有时候需要⽣产环境部署后,⼜需要Swagger的⽂档调试功能,辅助开发者调试,但是存在安全隐患,没有对Swagger的资源接⼝

过滤

Knife4j基于Servlet体系提供了过滤Filter功能,如果开发者使⽤SpringBoot开发框架进⾏开发的话,只需在ties或

者配置⽂件中配置相关属性即可⽅便的解决上⾯的问题,不⽤删除Springfox-swagger的jar包或者删除相关代码等复杂的

操作,提升开发体验。

资源屏蔽

⽬前Springfox-Swagger以及Knife4j提供的资源接⼝包括如下

资源说明

/ife4j提供的⽂档访问地址

/v2/api-docs-ext

Knife4j提供的增强接⼝地址,⾃2.0.6版本后删除

/swagger-resourcesSpringfox-Swagger提供的分组接⼝

/v2/api-docsSpringfox-Swagger提供的分组实例详情接⼝

/ringfox-Swagger提供的⽂档访问地址

/swagger-resources/configuration/uiSpringfox-Swagger提供

/swagger-resources/configuration/curitySpringfox-Swagger提供

资源说明

项⽬发布到⽣产环境之后，我们需要屏蔽swagger相关的资源，由于Knife4j基于Servlet体系提供了过滤Filter功能，所以就不需要我

们再去造轮⼦了，直接使⽤即可。

springboot只需要在配置⽂件中做如下修改即可

knife4j:

#开启增强配置

enable:true

#开启⽣产环境屏蔽

production:true

然后重启项⽬

如果看到如下信息，说明资源已经屏蔽成功，但是你⼜不想在⽣产环境中屏蔽swagger资源，只想给⼀部分⼈使⽤，也是可以的，加⼊权

限校验即可。

访问页⾯加权控制

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

简单点说，指定⼀个⽤户名和密码，访问Swagger⽂档需要验证登录名和密码，验证通过之后才能正常访问。

knife4允许开发者在配置⽂件（/properties）中增加⼀组⽤户名和密码。

knife4j:

#开启增强配置

enable:true

#开启Swagger的Basic认证功能,默认是fal

basic:

enable:true

#Basic认证⽤户名

urname:test

#Basic认证密码

password:123

如果⽤户开启了basic（=true）认证功能，但是没有指定urname和password，那么knife4j提供了⼀组默

认的⽤户名密码

admin/123321

配置好⽂件之后，我们再次重启项⽬（这个时候需要将之前设置的资源屏蔽需要去掉哦）

接⼝排序

我们在开发中，⼀个controller中往往会存在很多的接⼝，这样我们在⽂档查找的时候就会变得很苦恼，所以knife4j在

@ApiOperationSupport注解中增加了order字段,⽤于接⼝排序。

在使⽤此注解之前需要开启增强功能。

package;

importApiOperationSupport;

importApiSupport;

importApi;

importApiImplicitParam;

importApiOperation;

importGetMapping;

importRequestMapping;

importRequestParam;

importRestController;

@RestController

@RequestMapping(value="/test")

@ApiSupport(author="逆流星007-controller")

@Api(tags="测试swagger")

publicclassKnife4jTestController{

@GetMapping(value="/hello1")

@ApiImplicitParam(name="name",value="姓名",required=true)

@ApiOperation("测试接⼝01")

@ApiOperationSupport(author="逆流星逆流星007-test",order=1)

publicStringtest01(@RequestParam("name")Stringname){

return"hello"+name+",Iammeimeihan";

}

@GetMapping(value="/hello3")

@ApiImplicitParam(name="name",value="姓名",required=true)

@ApiOperation("测试接⼝03")

@ApiOperationSupport(author="逆流星逆流星007-test",order=3)

publicStringtest03(@RequestParam("name")Stringname){

return"hello"+name+",Iammeimeihan";

}

@GetMapping(value="/hello2")

@ApiImplicitParam(name="name",value="姓名",required=true)

@ApiOperation("测试接⼝02")

@ApiOperationSupport(author="逆流星逆流星007-test",order=2)

publicStringtest02(@RequestParam("name")Stringname){

return"hello"+name+",Iammeimeihan";

}

}

分组排序

分组，顾名思义，就是多个controller之间的排序，开发者可以通过注解实现每个controller之间的排序，实现这个功能的注解⼀共有三

个，具体如下：

@ApiSupport

@ApiSort

@Api

这三个注解是存在优先级的，也就是说，当同时使⽤时，只会有⼀个注解⽣效，所以在使⽤的时候需要特别注意。优先级规则如下：

@ApiSupport>@ApiSort>@Api

controller之间的排序规则为降序，越⼤的排在越靠前，但是排序的最⼩值⼀定需要⼤于0。

@ApiSupport

@RestController

@RequestMapping(value="/test")

@ApiSupport(author="逆流星007-controller",order=999)

@Api(tags="测试swagger")

publicclassKnife4jTestController

@ApiSort

@RestController

@RequestMapping(value="/test")

@ApiSort(value=999)

@Api(tags="测试swagger")

publicclassKnife4jTestController

@Api

@RestController

@RequestMapping(value="/test")

@Api(tags="测试swagger",position=999)

publicclassKnife4jTestController

虽然@Api中的position字段也能实现controller之间的排序，但是该字段已经被knife4j标记为不推荐使⽤，所以还是推荐使⽤第⼀种

排序⽅式（@ApiSupport）。

请求参数缓存

我们在调试接⼝的时候，有的接⼝会有很多参数，当我们好不容易填好了所有的参数，由于我们不⼩⼼关闭了页⾯，下次再调试的时候发现

还需要再次将参数输⼊⼀遍，⼼态会爆炸吧，所以knife4j在⽂档管理中增加了⼀个选项：开启请求参数缓存。

勾选这个选项之后，你填写的参数将会被knife4j缓存，关闭页⾯也不会丢失，是不是很⼈性呢？

编写代码，准备数据

@PostMapping(value="/saveUr")

@ApiOperation("保存⽤户信息")

@ApiOperationSupport(author="逆流星逆流星007")

publicStringsaveUr(@RequestBodyUrDTOurDTO){

n("前端传递的⽤户信息："+urDTO);

return"savesuccess";

}

package;

importApiModel;

importApiModelProperty;

importGetter;

importSetter;

importToString;

@ApiModel("⽤户信息")

@Getter

@Setter

@ToString

publicclassUrDTO{

@ApiModelProperty(value="⽤户名")

privateStringurname;

@ApiModelProperty(value="性别")

privateStringgender;

@ApiModelProperty(value="⼿机号码")

privateStringphone;

}

我们⼀起来看看效果

不过你不能⾼兴的太早，缓存也不是⼀定会⽣效的，我已知的这两种情况，缓存将会失效，在使⽤的时候需要注意哦。

在字段的@ApiModelProperty注解中添加example（属性的⽰例值）属性，那么，knife4j将不会使⽤缓存，使⽤的是后端指定的

example。

publicclassUrDTO{

@ApiModelProperty(value="⽤户名",example="李雷")

privateStringurname;

@ApiModelProperty(value="性别",example="男")

privateStringgender;

@ApiModelProperty(value="⼿机号码",example="")

privateStringphone;

}

当域名发⽣改变时，所有缓存将会失效。

动态请求参数

作为开发，不知道⼤家有没有做过这种操作，接⼝参数并不是实体对象接收，⽽是Map，虽然我没这么做过，但是我见过别⼈这么写过，当

后端程序员使⽤Map接收参数的时候，Swaggerui会怎么展⽰呢？我们⼀起来模拟⼀下。

定义⼀个以Map接收参数的接⼝

@PostMapping(value="/saveUrForMap")

@ApiOperation("新增⽤户信息-map")

@ApiOperationSupport(author="逆流星007")

privateStringsaveUrForMap(MapurDTO){

n("前端传递的⽤户信息："+urDTO);

return"savesuccess";

}

我们来看看Swaggerui如何展⽰这个Map类型的参数

这。。。。。要是前端看到这样的接⼝⽂档，⼼⾥开始问候后端的家⼈了吧，如何解决这个问题呢？其实很简单，knife4j早已为我们想到

了解决⽅案，招到⽂档管理-个性化设置，勾选开启动态请求参数就能解决这个问题了。

我们现在再来看看勾选了开启动态请求参数之后的效果

在输⼊了⼀个参数之后，参数列表会⾃动追加新的⼀⾏，但是参数的key却需要前端⼈员⾃⼰填写，前端有很⼤可能是不知道参数的key，

所以还是需要找后端开发⼈员，虽然开启了动态参数可以增加参数的个数，但是还没没有办法解决参数值的问题，那这个怎么解决呢？那这

就是另外⼀个增强功能了：动态请求参数添加⽂档注释

过滤请求参数

我们在开发过程中，经常会遇到这样的⼀个问题，新增和修改接⼝，修改接⼝需要传递修改的记录id，但是新增则不需要，⽽后端往往会将

修改和新增的⼊参对象设置为⼀个对象，那么这个对象中必然会存在id字段，这就会对新增造成误导，前端可能百思不得其解，新增的id

我应该怎么传呢？总不可能去偷⼀个吧。

所以，knife4j⽀持了请求参数的过滤（忽略），实现⽅式也是⾮常的简单，使⽤⾃定义增强注解ApiOperationSupport中

的ignoreParameters属性,可以强制忽略要显⽰的参数。

使⽤字段忽略之前我们得先了解⼀下字段忽略的规则：

1.例如新增接⼝时,某实体类不需要显⽰Id,即可使⽤该属性对参数进⾏忽略.ignoreParameters={"id"}

2.如果存在多个层次的参数过滤,则使⽤名称.属性的⽅式,例如ignoreParameters={"",""},其中uptModel是实体

对象参数名称,id为其属性,uptPo为实体类,作为uptModel类的属性名称

3。如果参数层级只是⼀级的情况下,并且参数是实体类的情况下,不需要设置参数名称,直接给定属性值名称即可

4.如果实体类属性中是通过List这种数组的⽅式,那么过滤规则会有所不同,在属性后⾯需要追加⼀个下标[0]，ignoreParameters=

{"[0].id"}

实现此功能需要开启增强功能。

表单提交和JSON提交的格式是不⼀样的，所以这⾥需要分开讲解⼀下，我们先来看表单提交怎么忽略字段属性。

前置条件：我们先创建两个DTO⽤来接收前端传递⼆点参数

package;

importApiModel;

importApiModelProperty;

importGetter;

importSetter;

importToString;

@ApiModel("⽤户信息")

@Getter

@Setter

@ToString

publicclassUrDTO{

@ApiModelProperty(value="⽤户id")

privateLongid;

@ApiModelProperty(value="⽤户名",example="李雷")

privateStringurname;

@ApiModelProperty(value="性别",example="男")

privateStringgender;

@ApiModelProperty(value="⼿机号码",example="")

privateStringphone;

@ApiModelProperty(value="⽤户收货地址信息")

privateUrAddressDTOurAddressDTO;

}

package;

importApiModelProperty;

importGetter;

importSetter;

importToString;

@Getter

@Setter

@ToString

publicclassUrAddressDTO{

@ApiModelProperty(value="收获地址的记录id")

privateLongid;

@ApiModelProperty(value="省")

privateStringprovince;

@ApiModelProperty(value="市")

privateStringcity;

@ApiModelProperty(value="区")

privateStringdistrict;

@ApiModelProperty(value="详细地址")

privateStringaddr;

}

表单提交

创建新增接⼝和修改接⼝，并且希望在添加的时候过滤掉UrDTO中的id字段与UrAddressDTO中的id字段，因为新增⽤户和收

获地址的时候是没有id信息的，只有新增完成之后才会存在id字段。

@ApiOperationSupport(author="逆流星007",ignoreParameters={"id",""})

@PostMapping(value="/saveUr")

@ApiOperation("新增⽤户信息-表单")

@ApiOperationSupport(author="逆流星007",ignoreParameters={"id",""})

publicStringsaveUr(UrDTOurDTO){

n("前端传递的⽤户信息："+urDTO);

return"savesuccess";

}

@PostMapping(value="/updateUr")

@ApiOperation("编辑⽤户信息")

@ApiOperationSupport(author="逆流星007")

publicStringupdateUr(UrDTOurDTO){

n("前端传递的⽤户信息："+urDTO);

return"editsuccess";

}

在过滤字段的时候，第⼀层我们只要填写对象中的属性名即可，但如果需要过滤第⼆层，根据忽略规则中的第⼆条，我们在UrDTO对象

中引⼊UrAddressDTO对象：privateUrAddressDTOurAddressDTO;我们还需要忽略UrAddressDTO对象中的id属性，那么需

要填上，其中urAddressDTO要与UrDTO对象中的UrAddressDTO属性名⼀致。

代码写好了，我们⼀起来看看效果。

添加接⼝

这⾥我们看不到UrDTO中的id，同时也看不到UrAddressDTO中的id，忽略成功。

修改接⼝

由于我们在修改的时候并没有忽略这两个字段，所以可以正常显⽰，这也是没有问题的。

JSON提交

由于表单提交和json提交的格式存在⼀定的差异，所以他们忽略参数的格式也存在⼀定的差异，我们将原来的修改和修改接⼝的参数接收

⽅式改为json格式并且保持和表单提交⼀样的忽略格式（为了看到更明显的效果，我在多忽略⼀个字段：“urname”）。

@ApiOperationSupport(author="逆流星007",ignoreParameters={"id",""})

@PostMapping(value="/saveUr")

@ApiOperation("新增⽤户信息")

@ApiOperationSupport(author="逆流星007",ignoreParameters={"id",""})

publicStringsaveUr(@RequestBodyUrDTOurDTO){

n("前端传递的⽤户信息："+urDTO);

return"savesuccess";

}

@PostMapping(value="/updateUr")

@ApiOperation("编辑⽤户信息")

@ApiOperationSupport(author="逆流星007")

publicStringupdateUr(@RequestBodyUrDTOurDTO){

n("前端传递的⽤户信息："+urDTO);

return"savesuccess";

}

我们先来看看效果会是什么样⼦？是否能够成功忽略呢？

新增接⼝

哦吼，居然也忽略成功了，卧槽，这打脸的也太快了，UrDTO中被忽略⼀个字段：id，，UrAddressDTO对象我忽略了id字段，我

们查看ui界⾯发现确实忽略成功了，这是怎么回事呢？具体为啥，我也不太清楚，可能是3.x做了升级，忽略⽅式和表单⼀致了，也许是

3.x不太稳定，出现了诡异的bug，导致了json格式也能这样忽略，虽然这样同样可以忽略成功，由于我不确定是⾼版本做了优化没有更

新⽂档还是诡异bug导致，我还是继续介绍⼀下json格式参数的忽略格式，有可能同学们这样使⽤却是不可以的，我推荐还是按照下⾯的

格式编写。

json格式如何忽略呢？

专业说法是：实例名.属性名，以新增⽤户为例，我们需要过滤⽤户id，那么写法就是：，其中urDTO为saveUr()的参

数名。

现在我们来改造⼀下我们的代码

@PostMapping(value="/saveUr")

@ApiOperation("新增⽤户信息")

@ApiOperationSupport(author="逆流星逆流星007",ignoreParameters={"",""})

publicStringsaveUr(@RequestBodyUrDTOurDTO){

n("前端传递的⽤户信息："+urDTO);

return"savesuccess";

}

我们⼀起来看看效果

这⾥还有⼀个情况是需要注意的，如果你忽略的字段在对象的第⼆层，那么在请求⽰例中，将会看不到完成的⽰例代码，会缺⽄少两，可能

3.x的bug吧，所以开头我申明过，3.x⽬前可能还不够稳定，升级或者使⽤的同学还是需要慎重啊。

搜索API接⼝

在⽂档的右上⾓,Knife4j提供了⽂档检索的功能

那这个搜索框都⽀持哪些关键字搜索呢？

接⼝地址。

接⼝名称。

接⼝描述。

以上三个搜索都是模糊搜索，但是，需要注意的是：⽬前检索功能仅对当前分组下的已经加载的接⼝有效,对于分组中的接⼝，没有加载的情

况下是搜索不到的,这点需要注意,换句话说该检索功能并⾮是全局检索,只对当前你看到的整体所有接⼝列表进⾏检索。

版本要求：knife4j版本>2.0.1使⽤此规则。

全局参数

Knife4j提供基于UI临时设置全局参数功能,例如后台全局token参数等.提供该功能主要是⽅便开发者进⾏调试

⽬前全局参数功能主要提供两种参数类型：query(表单)、header(请求头)

如果后端Swagger有配置全局参数，该功能可以⽆视

功能⽬录：⽂档管理->全局参数设置

⾃定义主页内容

不知道⼤家有没有觉得swagger的⾸页有⼀种很丑的感觉？是不是很不想看到它呢？那么接下来这条增强功能，决定是你的福利

啊，knife4j⽀持开发者⾃⼰替换⾸页，不过⽬前只⽀持md格式。

需要开启增强功能。

Knife4j⾃2.0.8版本开始,开发者可以提供⼀个Markdown⽂件来⾃定义显⽰Home主页的显⽰内容，通过配置yml来进⾏开启，配置⽂件如

下

knife4j:

enable:true

tting:

enableHomeCustom:true

homeCustomLocation:classpath:markdown/

属性说明：

enableHomeCustom:该属性为Boolean值,默认fal，如果开发者要⾃定义主页内容,该选项设置为true

homeCustomLocation:提供⼀个主页的Markdown⽂件位置

我们先在resources⽬录下创建⼀个markdown⽬录，然后在markdown⽬录下创建

昵称：逆流星007

职业：java开发⼯程

开源博客地址：ps:///qq_33220089

联系邮箱：361426201@

上⾯是的内容，接下来我们重启项⽬，⼀起来看看效果

咦，为什么没有发⽣改变呢？明明已经修改了啊，别急，我们忘记了最核⼼的⼀步，所以它没有替换成功，开发者需要在创建Docket逻辑分

组对象时，通过Knife4j提供的⼯具对象OpenApiExtensionResolver将扩展属性进⾏赋值。

package;

importOpenApiExtensionResolver;

importAutowired;

importBean;

importConfiguration;

importApiInfoBuilder;

importPathSelectors;

importRequestHandlerSelectors;

importContact;

importDocumentationType;

importDocket;

importEnableSwagger2;

@Configuration

@EnableSwagger2

publicclassKnife4jConfiguration{

privatefinalOpenApiExtensionResolveropenApiExtensionResolver;

@Autowired

publicKnife4jConfiguration(OpenApiExtensionResolveropenApiExtensionResolver){

iExtensionResolver=openApiExtensionResolver;

}

@Bean(value="defaultApi2")

publicDocketdefaultApi2(){

StringgroupName="3.X版本";

Docketdocket=newDocket(_30)

.apiInfo(newApiInfoBuilder()

.title("这是knife4jAPI")

.description("#这⾥记录服务端所有的接⼝的⼊参，出参等等信息")

.termsOfServiceUrl("")

.contact(newContact("逆流星","","361426201@"))

.version("3.0")

.build())

//分组名称

.groupName(groupName)

.lect()

//这⾥指定Controller扫描包路径

.apis(ckage("ller"))

.paths(())

.build()

.extensions(ettingExtensions());

returndocket;

}

}

通过上⾯⽰例代码，主要步骤如下：

1、通过@Autowired注解引⼊Knife4j向Spring容器注⼊的Bean对象OpenApiExtensionResolver

2、最终在Dcoket对象构建后，通过调⽤Docket对象的extensions⽅法进⾏插件赋值

3、插件赋值需要调⽤OpenApiExtensionResolver提供的buildSettingExtensions⽅法，获取x-ttings的增强属性

这样，我们就能看到效果了。

禁⽤调试

在以前的版本中，开发者如果要禁⽤调试功能，是通过在服务端创建UiConfiguration的实体Bean对象，配置supportMethod来达到禁⽤

部分接⼝的调试，⾃2.0.8版本后，该属性被废弃

此功能需要开启增强模式才能使⽤

如果开发者需要禁⽤调试功能，只需要在配置⽂件中进⾏操作即可

knife4j:

enable:true

tting:

enableDebug:fal

属性说明：

enableDebug:该属性是⼀个Boolean值，代表是否启⽤调试功能,默认值为true(代表开启调试)，如果要禁⽤调试，该值设为fal

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

4j;

iExtensionResolver;

red;

;

uration;

oBuilder;

lectors;

tHandlerSelectors;

t;

ntationType;

;

Swagger2;

@Configuration

@EnableSwagger2

publicclassKnife4jConfiguration{

privatefinalOpenApiExtensionResolveropenApiExtensionResolver;

@Autowired

publicKnife4jConfiguration(OpenApiExtensionResolveropenApiExtensionResolver){

iExtensionResolver=openApiExtensionResolver;

}

@Bean(value="defaultApi2")

publicDocketdefaultApi2(){

StringgroupName="3.X版本";

Docketdocket=newDocket(_30)

.apiInfo(newApiInfoBuilder()

.title("这是knife4jAPI")

.description("#这⾥记录服务端所有的接⼝的⼊参，出参等等信息")

.termsOfServiceUrl("")

.contact(newContact("逆流星","","361426201@"))

.version("3.0")

.build())

//分组名称

.groupName(groupName)

.lect()

//这⾥指定Controller扫描包路径

.apis(ckage("ller"))

.paths(())

.build()

.extensions(ettingExtensions());

returndocket;

}

}

全部操作完成之后，重启项⽬看效果

调试和open按钮没有了。

禁⽤搜索框

发者如果想要禁⽤Ui界⾯中的搜索功能，需要通过增强属性进⾏配置，此功能需要开启增强功能。

knife4j:

enable:true

tting:

enableSearch:fal

属性说明：

enableSearch:该属性是⼀个Boolean值，代表是否启⽤搜索功能,默认值为true(代表开启搜索)，如果要禁⽤搜索，该值设为fal

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

体的代码实现请参考禁⽤调试和⾃定义主页内容，我这⾥就不重复了。

重启项⽬看效果

好了，knife4j的介绍到这⾥就结束了，还有⼀些⾼级的功能，就需要⼤家⾃⼰慢慢的摸索了，本⽂⼤部分参考了knife4j的官⽅⽂档，⾃

⼰写的demo，如果觉得对您有帮助，希望留下您宝贵的⼀赞。