什么是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包中,并且后续也会满足开发者更多的个性化需求.
主要的变化是,项目的相关类包路径更换为com.github.xiaoymin.knife4j前缀,开发者使用增强注解时需要替换包路径
后端Java代码和ui包分离为多个模块的jar包,以面对在目前微服务架构下,更加方便的使用增强文档注解(使用SpringCloud微服务项目,只需要在网关层集成UI的jar包即可,因此分离前后端)
knife4j沿用swagger-bootstrap-ui的版本号,第1个版本从1.9.6开始,关于使用方法,请参考文档。
怎么使用knife4j
第一步:在maven项目的pom.xml
中引入Knife4j的依赖包,代码如下:
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.7</version> </dependency>
第二步:创建Swagger配置依赖,代码如下:
package com.maple.rest.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.EnableSwagger2WebMvc; /** * @author 笑小枫 * @date 2022/6/28 */ @Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration { @Bean(value = "example") public Docket example() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() .title("笑小枫实例演示接口") .description("笑小枫实例演示接口") .termsOfServiceUrl("http://127.0.0.1:6666") .contact(new Contact("笑小枫", "http://www.xiaoxiaofeng.site", "zfzjava@163.com")) .version("1.0") .build()) //分组名称 .groupName("演示实例接口") .select() //这里指定Controller扫描包路径 .apis(RequestHandlerSelectors.basePackage("com.maple.rest.controller.example")) .paths(PathSelectors.any()) .build(); } }
第三步:创建一个Controller
package com.maple.rest.controller.example; import io.swagger.annotations.Api; import io.swagger.annotations.ApiModelProperty; import io.swagger.annotations.ApiOperation; import lombok.Data; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; /** * @author zhangfuzeng * @date 2022/6/30 */ @Api(tags = "实例演示-Knife4j接口文档") @RestController @RequestMapping("/example") public class TestKnife4jController { @ApiOperation(value = "Knife4j接口文档演示") @GetMapping("/testKnife4j") public Test testKnife4j(Test param) { Test test = new Test(); test.setName("笑小枫"); test.setAge(18); test.setRemark("大家好,我是笑小枫,喜欢我的小伙伴点个赞呗,欢迎访问我的个人博客:http://www.xiaoxiaofeng.site"); return test; } @Data static class Test { @ApiModelProperty(value = "姓名") private String name; @ApiModelProperty(value = "年龄") private Integer age; @ApiModelProperty(value = "描述") private String remark; } }
看下页面效果
接口文档总览:
接口调试:
增强模式
Knife4j自2.0.6版本开始,将目前在Ui界面中一些个性化配置剥离,开发者可以在后端进行配置,并且提供的knife4j-spring-boot-strater组件自动装载
spring.factories配置如下:
# Auto Configure org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration
在Spring Boot配置文件中,完整的配置如下:
knife4j: enable: true documents: - group: 2.X版本 name: 接口签名 locations: classpath:sign/* setting: language: zh-CN enableSwaggerModels: true enableDocumentManage: true swaggerModelName: 实体类列表 enableVersion: false enableReloadCacheParameter: false enableAfterScript: true enableFilterMultipartApiMethodType: POST enableFilterMultipartApis: false enableRequestCache: true enableHost: false enableHostText: 192.168.0.193:8000 enableHomeCustom: true homeCustomLocation: classpath:markdown/home.md enableSearch: false enableFooter: false enableFooterCustom: true footerCustomContent: Copyright 2022-[笑小枫](http://www.xiaoxiaofeng.site) enableDynamicParameter: false enableDebug: true enableOpenApi: false enableGroup: true cors: false production: false basic: enable: false username: test password: 12313
在以前的版本中,开发者需要在配置文件中手动使用@EnableKnife4j来使用增强,自2.0.6版本后,只需要在配置文件中配置knife4j.enable=true即可不在使用注解
注意:要使用Knife4j提供的增强,knife4j.enable=true
必须开启
各个配置属性说明如下:
'
属性 | 默认值 | 说明值 |
knife4j.enable | false | 是否开启Knife4j增强模式 |
knife4j.cors | false | 是否开启一个默认的跨域配置,该功能配合自定义Host使用 |
knife4j.production | false | 是否开启生产环境保护策略,详情参考文档 |
knife4j.basic | 对Knife4j提供的资源提供BasicHttp校验,保护文档 |
knife4j.basic.enable | false | 关闭BasicHttp功能 |
knife4j.basic.username | basic用户名 | |
knife4j.basic.password | basic密码 |
knife4j.documents | 自定义文档集合,该属性是数组 | |
knife4j.documents.group | 所属分组 | |
knife4j.documents.name | 类似于接口中的tag,对于自定义文档的分组 |
knife4j.documents.locations | markdown文件路径,可以是一个文件夹(classpath:markdowns/* ),也可以是单个文件(classpath:md/sign.md ) |
|
knife4j.setting | 前端Ui的个性化配置属性 |
knife4j.setting.enableAfterScript | true | 调试Tab是否显示AfterScript功能,默认开启 |
knife4j.setting.language | zh-CN | Ui默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US) |
knife4j.setting.enableSwaggerModels | true | 是否显示界面中SwaggerModel功能 |
knife4j.setting.swaggerModelName | Swagger Models |
重命名SwaggerModel名称,默认 |
knife4j.setting.enableDocumentManage | true | 是否显示界面中"文档管理"功能 |
knife4j.setting.enableReloadCacheParameter | false | 是否在每个Debug调试栏后显示刷新变量按钮,默认不显示 |
knife4j.setting.enableVersion | false | 是否开启界面中对某接口的版本控制,如果开启,后端变化后Ui界面会存在小蓝点 |
knife4j.setting.enableRequestCache | true | 是否开启请求参数缓存 |
knife4j.setting.enableFilterMultipartApis | false | 针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址 |
knife4j.setting.enableFilterMultipartApiMethodType | POST | 具体接口的过滤类型 |
knife4j.setting.enableHost | false | 是否启用Host |
knife4j.setting.enableHomeCustom | false | 是否开启自定义主页内容 |
knife4j.setting.homeCustomLocation | 主页内容Markdown文件路径 |
knife4j.setting.enableSearch | false | 是否禁用Ui界面中的搜索框 |
knife4j.setting.enableFooter | true | 是否显示Footer |
knife4j.setting.enableFooterCustom | false | 是否开启自定义Footer |
knife4j.setting.footerCustomContent | false | 自定义Footer内容 |
knife4j.setting.enableDynamicParameter | false | 是否开启动态参数调试功能 |
knife4j.setting.enableDebug | true | 启用调试 |
knife4j.setting.enableOpenApi | true | 显示OpenAPI规范 |
knife4j.setting.enableGroup | true | 显示服务分组 |
关于个性化文档(knife4j.documents
)以及个性化设置(knife4j.setting
),有一些细微的区别,开发者在配置文件中进行配合好后,还需要在创建Docket对象时调用Knife4j
提供的扩展Extesions进行赋值
示例代码如下:
package com.maple.rest.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.EnableSwagger2WebMvc; /** * @author 笑小枫 * @date 2022/6/28 */ @Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration { /*引入Knife4j提供的扩展类*/ private final OpenApiExtensionResolver openApiExtensionResolver; @Autowired public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) { this.openApiExtensionResolver = openApiExtensionResolver; } @Bean(value = "example") public Docket example() { String groupName="演示实例接口"; return new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() .title("笑小枫实例演示接口") .description("笑小枫实例演示接口") .termsOfServiceUrl("http://127.0.0.1:6666") .contact(new Contact("笑小枫", "http://www.xiaoxiaofeng.site", "zfzjava@163.com")) .version("1.0") .build()) //分组名称 .groupName(groupName) .select() //这里指定Controller扫描包路径 .apis(RequestHandlerSelectors.basePackage("com.maple.rest.controller.example")) .paths(PathSelectors.any()) .build() //赋予插件体系 .extensions(openApiExtensionResolver.buildExtensions(groupName)); } }
buildExtensions方法需要传入分组名称,该分组名称主要是为了区分开发者在构建自定义文档时,在不同的Docket逻辑分组下进行区别显示。
OpenApiExtensionResolver辅助类需要配置knife4j.enable=true才能自动@Autowired
增强效果开启后,在最终调用接口时,Knife4j会添加扩展属性x-openapi,如下图:
更多功能,请参考官方文档:https://doc.xiaominfo.com/knife4j/
关于笑小枫
本章到这里结束了,喜欢的朋友关注一下我呦,大伙的支持,就是我坚持写下去的动力。
老规矩,懂了就点赞收藏;不懂就问,日常在线,我会就会回复哈~
后续文章会陆续更新,文档会同步在微信公众号、个人博客、CSDN和GitHub保持同步更新。
微信公众号:笑小枫
笑小枫个人博客:http://www.xiaoxiaofeng.site