实战SpringBoot系列 - 让Swagger跌下神坛的Knife4j使用详解
实战架构师2021-05-15 21:09
1、简介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包即可,因此分离前后端)
1.1、核心功能
该UI增强包主要包括两大核心功能：文档说明 和 在线调试
文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，使用swagger-bootstrap-ui能根据该文档说明，对该接口的使用情况一目了然。在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，而不必通过其他测试工具测试接口是否正确,简介、强大。1.2、UI增强
同时，swagger-bootstrap-ui在满足以上功能的同时，还提供了文档的增强功能，这些功能是官方swagger-ui所没有的，每一个增强的功能都是贴合实际,考虑到开发者的实际开发需要,是比不可少的功能，主要包括：
个性化配置：通过个性化ui配置项，可自定义UI的相关显示信息离线文档：根据标准规范，生成的在线markdown离线文档，开发者可以进行拷贝生成markdown接口文档，通过其他第三方markdown转换工具转换成html或pdf，这样也可以放弃swagger2markdown组件接口排序：自1.8.5后，ui支持了接口排序功能，例如一个注册功能主要包含了多个步骤,可以根据swagger-bootstrap-ui提供的接口排序规则实现接口的排序，step化接口操作，方便其他开发者进行接口对接2、实战2.1.1、效果图
2.1.1.1、首页：
2.1.1.2、调试：
2.2.2、修改pom.xml
通常情况我们只需要引入 knife4j 的依赖即可，但是有时会出现 guava 的版本冲突，所以，可以把 guava 一起引入进来
2.2.3、创建配置类
整体配置与 Swagger2 几乎一致，扫描 controller 所在的包
2.2.4、修改启动类
放开静态资源的访问，启动类实现 WebMvcConfigurer 接口，重写 addResourceHandlers 方法
2.2.5、访问文档
启动项目，访问knife4j路径
http://localhost:8080/doc.html
注意：访问时，如果提示 knife4j 文档异常，检查下自己的拦截器是否没有放开 knife4j 所需要的请求
配置拦截器，放开请求：
2.2.6、示例代码
2.2.6.1 控制层
2.2.6.2 model类
统一返回类：
用户类：
3、测试项目启动成功后访问，ip+端口/doc.html，如：访问：http://localhost:8080/doc.html
3.1、getUser（Get请求）
3.2、saveUser（Post请求）
3.3、上传
3.4、下载
举报/反馈
0
0
收藏
分享
