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

前言

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

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

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

但是不知道大家有没有发现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查看

功能

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

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

二、swagger-ui-layer

简介

开源地址: Gitee

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

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

官网演示的截图

三、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查看

功能

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

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