再见丑陋的 SwaggerUI，这款开源的API文档生成神器界面更炫酷，逼格更高
一般在使用 Spring Boot 开发前后端分离项目的时候，都会用到 Swagger。Swagger 是一个规范和完整的框架，用于生成、描述、调试和可视化 RESTful 风格的 Web API 服务框架。
但随着系统功能的不断增加，接口数量的爆炸式增长，Swagger 的使用体验就会变得越来越差，比如请求参数为 JSON 的时候没办法格式化，返回结果没办法折叠，还有就是没有提供搜索功能。
刚好最近发现 Knife4j 弥补了这些不足，赋予了 Swagger 更强的生命力，于是就来给大家安利一波。
一、关于 Knife4j
Knife4j 的前身是 swagger-bootstrap-ui，是 springfox-swagger-ui 的增强 UI 实现。swagger-bootstrap-ui 采用的是前端 UI 混合后端 Java 代码的打包方式，在微服务的场景下显得非常臃肿，改良后的 Knife4j 更加小巧、轻量，并且功能更加强大。
springfox-swagger-ui 的界面长这个样子，说实话，确实略显丑陋。
swagger-bootstrap-ui 增强后的样子长下面这样。单纯从直观体验上来看，确实增强了。
改良后的 Knife4j 不仅在界面上更加优雅、炫酷，功能上也更加强大：后端 Java 代码和前端 UI 模块分离了出来，在微服务场景下更加灵活；更提供了专注于 Swagger 的增强解决方案。
官方文档：
https://doc.xiaominfo.com/knife4j/documentation/
码云地址：
https://gitee.com/xiaoym/knife4j
示例地址：
https://gitee.com/xiaoym/swagger-bootstrap-ui-demo
二、整合 Swagger
为了对比 Knife4j 和 Swagger，我们先来整合体验一把 Swagger。
第一步，在 pom.xml 中添加 springfox 的官方 Swagger 依赖：
<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>
第二步，添加 Swagger 的 Java 配置，只需要配置基本的 API 信息和需要扫描的类路径即可。
@Configuration
public class SwaggerConfig {@Beanpublic Docket docket() {Docket docket = new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).enable(true).select()//apis： 添加swagger接口提取范围.apis(RequestHandlerSelectors.basePackage("com.codingmore.controller")).paths(PathSelectors.any()).build();return docket;}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("编程猫学习网站的 admin 管理端 API").description("codingmore").contact(new Contact("沉默王二&石磊", "https://tobebetterjavaer.com", "983436076@qq.com")).version("1.0").build();}
}
第二步，访问 API 文档，访问地址如下所示：
http://localhost:9002/swagger-ui/
在项目路径后面添加上 swagger-ui 就可以了。
在 Controller 类中，可以看到常见的 Swagger 注解 @Api 和 @ApiOperation：
@Controller
@Api(tags = "文章 ")
@RequestMapping("/posts")
public class PostsController {@RequestMapping(value = "/delete", method = RequestMethod.GET)@ResponseBody@ApiOperation("删除")public ResultObject<String> delete(long postsId) {return ResultObject.success(postsService.removePostsById(postsId) ? "删除成功" : "删除失败");}
}
@Api 注解用在类上，该注解将一个 Controller 类标记位一个 Swagger 资源（API）。默认情况下，Swagger 只会扫描解析具有 @Api 注解的类。
@ApiOperation 注解用在方法上，该注解在指定的方法上，对一个方法进行描述。
Swagger 还有很多其他的注解，比如说 @ApiParam、@ApiResponses 等等，这里就不再一一说明。
三、整合 Knife4j
Knife4j 完全遵循了 Swagger 的使用方式，所以可以无缝切换。
第一步，在 pom.xml 文件中添加 Knife4j 的依赖（不需要再引入 springfox-boot-starter）。
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><!--在引用时请在maven中央仓库搜索3.X最新版本号--><version>3.0.2</version>
</dependency>
第二步，在 Java 配置类上添加 @EnableOpenApi 注解，开启 Knife4j 增强功能。
@Configuration
@EnableOpenApi
public class SwaggerConfig {}
第三步，重新运行 Spring Boot 项目，访问 API 文档，查看效果。
访问地址：http://localhost:9002/doc.html
如果项目中加了权限认证的话，记得给 Knife4j 添加白名单。我的项目用的是 SpringSecurity，所以需要在 application.yml 文件中添加。
secure:ignored:urls: #安全路径白名单- /doc.html- /swagger-ui/**- /swagger/**- /swagger-resources/**- /**/v3/api-docs
四、Knife4j 的功能特点
1）支持登录认证
Knife4j 和 Swagger 一样，也是支持头部登录认证的，点击「authorize」菜单，添加登录后的信息即可保持登录认证的 token。
如果某个 API 需要登录认证的话，就会把之前填写的信息带过来。
2）支持 JSON 折叠
Swagger 是不支持 JSON 折叠的，当返回的信息非常多的时候，界面就会显得非常的臃肿。Knife4j 则不同，可以对返回的 JSON 节点进行折叠。
3）离线文档
Knife4j 支持把 API 文档导出为离线文档（支持 markdown 格式、HTML 格式、Word 格式），
使用 Typora 打开后的样子如下，非常的大方美观。
4）全局参数
当某些请求需要全局参数时，这个功能就很实用了，Knife4j 支持 header 和 query 两种方式。
之后进行请求的时候，就会把这个全局参数带过去。
5）搜索 API 接口
Swagger 是没有搜索功能的，当要测试的接口有很多的时候，当需要去找某一个 API 的时候就傻眼了，只能一个个去拖动滚动条去找。
在文档的右上角，Knife4j 提供了文档搜索功能，输入要查询的关键字，就可以检索筛选了，是不是很方便？
目前支持搜索接口的地址、名称和描述。
五、尾声
除了我上面提到的增强功能，Knife4j 还提供了很多实用的功能，大家可以通过官网的介绍一一尝试下，生产效率会提高不少。
https://doc.xiaominfo.com/knife4j/documentation/enhance.html
如果项目中之前使用过 Swagger 生成接口文档，切换到 Knife4j 可以说是非常的丝滑，只需要两步：
- 在 pom.xml 文件中把
springfox-boot-starter替换为knife4j-spring-boot-starter； - 访问地址由原来的
http://${host}:${port}/swagger-ui.html切换到http://${host}:${port}/doc.html，如果有权限限制的话，记得开白名单。
本篇已收录至 GitHub 上星标 1.4k+ star 的开源专栏《Java 程序员进阶之路》，该专栏风趣幽默、通俗易懂，对 Java 爱好者极度友好和舒适
欢迎关注方志朋的博客,回复"666"获面试宝典 一般在使用 Spring Boot 开发前后端分离项目的时候,都会用到 Swagger.Swagger 是一个规范和完整的框架,用于 ... apiDoc 一款很不错api文档生成工具,在开发接口的时候,需要给同事看相应的接口文档.给大家推荐一个生成文档的工具--apiDoc,最后生成的文档以网页的形式发布,方便快捷,便于阅读. 创建项目目 ... 文章目录 接口生成利器 knife 介绍 springboot 整合 knife pom.xml 文件增加依赖 编写Swagger2Config配置文件 注意事项 总结 knife Gitee 地址: ... 一种无侵入比swagger-ui兼容性更好更简单的API文档生成方案 一种无侵入比swagger-ui兼容性更好更简单的API文档生成方案 作者:互联网活化石 来源:http://suo.im/5Si ... 前言 最近公司打算做一个openapi开放平台,让我找一款好用的在线文档生成工具,具体要求如下: 必须是开源的 能够实时生成在线文档 支持全文搜索 支持在线调试功能 界面优美 说实话,这个需求看起来简 ... 导航: Word文档生成神器:开源项目poi-tl使用介绍 一. 概述 1.1 适合的场景 1.2 poi-tl的优势 二. poi-tl实例演示: 2.1 使用poi-tl生成word文档 三. 更 ... 以下文章来源方志朋的博客,回复"666"获面试宝典 介绍 smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,smart ... 在项目中,需要协同开发,所以会写许多API文档给其他同事,以前都是写一个简单的TXT文本或Word文档,口口相传,这种方式比较老土了,所以,需要有个api管理系统专门来管理这些api,从网上找了许多比 ... 在后端项目中,难免遇到需要写接口文档方便第三方调用的场景,一般业界最常用的方案是使用swagger.Java项目中,一般采用springfox项目,它集成了swagger和swagger-ui,不需要 ... 大家好,我是小孟,最近做了不少项目,后面会路线开源给大家. 做的这些项目的过程中,发现了一款接口文档的神器. 喜欢尝鲜的小伙伴可以纳拿去使用,可以找小孟一起交流呀. 也希望大家的技术一样棒棒的,然后搞 ...再见丑陋的 SwaggerUI，这款开源的API文档生成神器界面更炫酷，逼格更高相关推荐
最新文章
热门文章