SpringBoot项目实战：整合Swagger2构建强大的Restful Api接口文档（三）

微服务方向：springboot, springCloud, Dubbo

分布式/高并发： 分布式锁， 消息队列RabbitMQ

大数据处理： Hadoop, spark, HBase等

python方向： python web开发

一， 前言

原生的swagger-ui并不是很美观， 而且项目中如果出现了大量的api接口， 也不方便查看和调试。那么，这篇主要是说一下swagger-ui的界面优化这个事，来涨涨见识。

所以接下来我将介绍两款开源的Swagger-ui库，配置也很简单：

swagger-bootstrap-ui

swagger-ui-layer

二，整合swagger-bootstrap-ui

swagger-bootstrap-ui是基于swagger接口api实现的一套UI,因swagger原生ui是上下结构的，在浏览接口时不是很清晰,所以，swagger-bootstrap-ui是基于左右菜单风格的方式,适用与我们在开发后台系统左右结构这种风格类似,方便与接口浏览

Github地址:https://github.com/xiaoymin/Swagger-Bootstrap-UI

1.首先来看看效果图：

如上图， 接口文档就成了左右结构，如果感兴趣可以继续往下看，如何搭建的额。

2.将jar引入到pom文件中

io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0 com.github.xiaoymin swagger-bootstrap-ui 1.7.3

如上代码，对于swagger-ui和swagger-bootstrap-ui这两个包是可以共存的。

3.注意事项

注意，如果我们采用的是SpringBoot项目实战（二十三篇）：整合Swagger2构建强大的Restful Api接口文档（二）第二篇中的方式进行操作的话， 直接访问同样会出现Whitelabel Error Page的结果。如果不是，请忽略。

所以我们需要对webConfig类进行一个小小的完善，将 替换成 ，就可以映射所有的地址到该资源路径下查找。

/** * 此方法是用来添加静态资源映射的 * 发现如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效。 需要重新指定静态资源 */ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/**").addResourceLocations( "classpath:/static/"); /* registry.addResourceHandler("swagger-ui.html").addResourceLocations( "classpath:/META-INF/resources/");*/ registry.addResourceHandler("/**").addResourceLocations( "classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations( "classpath:/META-INF/resources/webjars/"); super.addResourceHandlers(registry); }

4. 启动项目，访问http://$:$/doc.html，观察结果

里面具体的如何操作， 可以自己扩展一下，查阅资料。

三，整合swagger-ui-layer

swagger-ui-layer是基于swagger接口api实现的一套基于layer的UI,因swagger原生ui是上下结构的，在浏览接口时不是很清晰,所以，swagger-ui-layer是基于左右菜单风格的方式,适用与我们在开发后台系统左右结构这种风格类似,方便与接口浏览

Github地址:https://github.com/caspar-chen/swagger-ui-layer

我偶然发现有另外一个作者在上面原作者的基础上有优化一些功能，我就引用的这一位作者的

他的Github的地址：https://github.com/ohcomeyes/swagger-ui-layer

1.首先来看看效果图：

如上图， 接口文档就成了左右结构，如果感兴趣可以继续往下看，如何搭建的额。

2.将jar引入到pom文件中

io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0 com.github.xiaoymin swagger-bootstrap-ui 1.7.3 com.github.ohcomeyes swagger-ui-layer 1.2

如上代码，对于swagger-ui和swagger-bootstrap-ui和swagger-ui-layer这三个包是可以共存的。

3.注意事项

注意，如果我们采用的是SpringBoot项目实战（二十三篇）：整合Swagger2构建强大的Restful Api接口文档（二）第二篇中的方式进行操作的话， 直接访问同样会出现Whitelabel Error Page的结果。如果不是，请忽略。

所以我们需要对webConfig类进行一个小小的完善，将 替换成 ，就可以映射所有的地址到该资源路径下查找。

/** * 此方法是用来添加静态资源映射的 * 发现如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效。 需要重新指定静态资源 */ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/**").addResourceLocations( "classpath:/static/"); /* registry.addResourceHandler("swagger-ui.html").addResourceLocations( "classpath:/META-INF/resources/");*/ registry.addResourceHandler("/**").addResourceLocations( "classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations( "classpath:/META-INF/resources/webjars/"); super.addResourceHandlers(registry); }

4. 启动项目，访问http://$:$/api-docs.html，观察结果

what?出现了白板， 也没有什么显示出来， 难道是不兼容问题。为啥上一个没有出现问题， 而这一个出现了问题。

我对比了swagger-ui与swagger-ui-layer的文档访问，来看看有什么不同呢？

swagger-ui访问正常的

swagger-ui-layer访问异常的

通过对比这两个请求，可以发现swagger-ui-layer在请求/api-docs地址上少

了group这个参数。

而这个group参数不就是我们在Swagger2中配置的

defaultApi()方法中有个groupName的配置， 而网上很多教程基本上都有配置这个参数，就给我们大家造成了误解，开始思考：那是否可以删除，默认没有呢？答案是可以不用配置。那么接下来我们删除一下，看是否可以成功。

删除后的代码如下：

然后我们启动项目，访问http://localhost:8080/api-docs.html

竟然成功了，里面具体的如何操作，跟swagger-ui类似， 可以自己扩展一下，查阅资料。

四，总结

SpringBoot整合Swagger也基本完成了，我花了一个下午时间，实践加写文章记录，还是比较辛苦和累，但是写完以后，再回过头来看的时候， 发现心中会有一种成就感由心而起，也希望可以帮助到大家一点点，可以关注我的微信公众号Rayson_666（Rayson开发分享）， 分享我学习和总结的经验给大家，并一起学习进步。