前言

相信无论是前端或是后端的程序员对Swagger都不怎么陌生,没有用过应该也听说过

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

给你的Swagger文档换套附魔皮肤吧-LMLPHP

简单的配置后,就能生成一份清晰的API文档。

给你的Swagger文档换套附魔皮肤吧-LMLPHP

但是不知道大家有没有发现Swagger原生的ui似乎并不支持对请求头的操作,在我之前整合JWT时遇到过这样的问题,当时的解决办法是设置全局参数。但对我来说还是花费了一些时间去学习,但是这样的方法只能适用于特定的请求头,耦合度很高,如果需要别的参数,还要再修改代码。

下面就介绍三种Swagger的增强ui

一、swagger-mg-ui

简介

开源地址Gitee

swagger-mg-ui是swagger的一个前端实现,使用简单、解析速度快、走心的设计,支持多项目同时展示,多种文档目录的展示方案,多种自定义配置,满足各种使用习惯。

使用

非常简单,只需要添加如下maven依赖即可

<!-- https://mvnrepository.com/artifact/com.zyplayer/swagger-mg-ui -->
<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

启动后访问:http://localhost:8080/document.html查看

给你的Swagger文档换套附魔皮肤吧-LMLPHP

功能

ui支持多种树形菜单展示方式,但我感觉有点不好的是,所有请求的颜色都是一样的,不像原生ui那样清晰明了。

swagger-mg-ui支持对请求头的设置,并且对请求做了持久化,会记录你测试过的请求,不过有点不好的是它是将数据存在了LocalStorage里,就是说如果测试的多了,会占一些空间。

给你的Swagger文档换套附魔皮肤吧-LMLPHP

给你的Swagger文档换套附魔皮肤吧-LMLPHP

二、swagger-ui-layer

简介

开源地址: Gitee

swagger-ui-layer 是一个基于swagger的前端UI实现,是为了替换了默认的swagger-ui,让生成的文档更加友好和美观。

swagger-ui-layer看名字也能知道这个ui和layui有点关系了,swagger-ui-layer确实是layui风格,但是很不幸的是此项目已经停止维护,不兼容最新的SpringBoot和Swagger。暂时放弃(就是个凑数的)

官网演示的截图

给你的Swagger文档换套附魔皮肤吧-LMLPHP

三、knife4j

简介

开源地址: Gitee

官网地址knife4j

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

knife4j的前身是swagger-bootstrap-ui,为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j

这应该是最好的一个Swagger增强项目了,目前仍在维护,并且是码云的GVP项目。另外值得一提的是此项目支持再SpringCloud微服务架构下使用,不需要在每个微服务下引入ui资源。功能之全恐怕我介绍不完,需要大家自己摸索。

使用

非常简单,同样是一个以来的事情

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>${lastVersion}</version>
</dependency>

然后启动项目访问:http://localhost:8080/doc.html查看

给你的Swagger文档换套附魔皮肤吧-LMLPHP

功能

这个ui的功能就像是整合进项目的PostMan,还贴心的做了一个标签页,支持设置请求头请求参数,支持导出文档离线阅读。

给你的Swagger文档换套附魔皮肤吧-LMLPHP

还有一个非常好用的功能是支持全局参数的设置,还记得我之前所说的JWT调试的事情吗,这个项目似乎就是为了调试JWT所生一般,只需添加全局请求头便能测试所有接口,非常的方便

给你的Swagger文档换套附魔皮肤吧-LMLPHP
用过都说好

08-26 18:48