作者：方雷
个人博客：http://blog.chargingbunk.cn/
微信公众号：rayson_666(Rayson开发分享)
个人专研技术方向：
- 微服务方向：springboot, springCloud, Dubbo
- 分布式/高并发： 分布式锁， 消息队列RabbitMQ
- 大数据处理： Hadoop, spark, HBase等
- python方向： python web开发
喜欢的朋友们可以关注我的简书或微信公众号(rayson_666), 一起交流学习， 后期会不断更新有经验的干货.
一， 前言
原生的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文件中
<!-- 构建Restful Api文档 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!--引入swagger-ui包-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<!--引入swagger-bootstrap-ui包-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.7.3</version>
</dependency>
如上代码，对于swagger-ui和swagger-bootstrap-ui这两个包是可以共存的。
3.注意事项
注意，如果我们采用的是SpringBoot项目实战（二十三篇）：整合Swagger2构建强大的Restful Api接口文档（二）第二篇中的方式进行操作的话， 直接访问同样会出现Whitelabel Error Page的结果。如果不是，请忽略。
所以我们需要对webConfig类进行一个小小的完善，将 swagger-ui.html 替换成 /**，就可以映射所有的地址到该资源路径下查找。
/**
* 此方法是用来添加静态资源映射的
* 发现如果继承了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://${host}:${port}/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文件中
<!-- 构建Restful Api文档 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!--引入swagger-ui包-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<!--引入swagger-bootstrap-ui包-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.7.3</version>
</dependency>
<!--引入swagger-ui-layer包-->
<dependency>
<groupId>com.github.ohcomeyes</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>1.2</version>
</dependency>
如上代码，对于swagger-ui和swagger-bootstrap-ui和swagger-ui-layer这三个包是可以共存的。
3.注意事项
注意，如果我们采用的是SpringBoot项目实战（二十三篇）：整合Swagger2构建强大的Restful Api接口文档（二）第二篇中的方式进行操作的话， 直接访问同样会出现Whitelabel Error Page的结果。如果不是，请忽略。
所以我们需要对webConfig类进行一个小小的完善，将 swagger-ui.html 替换成 /**，就可以映射所有的地址到该资源路径下查找。
/**
* 此方法是用来添加静态资源映射的
* 发现如果继承了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://${host}:${port}/api-docs.html，观察结果
what?出现了白板， 也没有什么显示出来， 难道是不兼容问题。为啥上一个没有出现问题， 而这一个出现了问题。
我对比了swagger-ui与swagger-ui-layer的文档访问，来看看有什么不同呢？
swagger-ui访问正常的
swagger-ui-layer访问异常的
通过对比这两个请求，可以发现swagger-ui-layer在请求/api-docs地址上少
了group这个参数。
而这个group参数不就是我们在Swagger2中配置的
/**
*
* Swagger2配置类
* @author 方雷(Rayson)
* @微信公众号: rayson_666(Rayson开发分享) 、
* 分享springBoot springCloud技术, 以及python,大数据学习系列
* @个人博客: http://blog.chargingbunk.cn/
* @简书: https://www.jianshu.com/u/5b0de5c8dc56
* 2018年6月9日
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket defaultApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("默认分组") // group就是指的这个
.select()
.apis(RequestHandlerSelectors
.basePackage("cn.rayson.controller"))
.paths(PathSelectors.any()).build();
}
// 预览地址:swagger-ui.html
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("利用swagger构建测试系统api文档")
.description("接口访问地址：http://localhost:8080/, by 方雷")
.termsOfServiceUrl("http://localhost:8080/")
//.contact("方雷")
.version("1.0")
.build();
}
}
defaultApi()方法中有个groupName的配置， 而网上很多教程基本上都有配置这个参数，就给我们大家造成了误解，开始思考：那是否可以删除，默认没有呢？答案是可以不用配置。那么接下来我们删除一下，看是否可以成功。
删除后的代码如下：
/**
*
* Swagger2配置类
* @author 方雷(Rayson)
* @微信公众号: rayson_666(Rayson开发分享) 、
* 分享springBoot springCloud技术, 以及python,大数据学习系列
* @个人博客: http://blog.chargingbunk.cn/
* @简书: https://www.jianshu.com/u/5b0de5c8dc56
* 2018年6月9日
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket defaultApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors
.basePackage("cn.rayson.controller"))
.paths(PathSelectors.any()).build();
}
}
// 预览地址:swagger-ui.html
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("利用swagger构建测试系统api文档")
.description("接口访问地址：http://localhost:8080/, by 方雷")
.termsOfServiceUrl("http://localhost:8080/")
//.contact("方雷")
.version("1.0")
.build();
}
}
然后我们启动项目，访问http://localhost:8080/api-docs.html
竟然成功了，里面具体的如何操作，跟swagger-ui类似， 可以自己扩展一下，查阅资料。
四，总结
SpringBoot整合Swagger也基本完成了，我花了一个下午时间，实践加写文章记录，还是比较辛苦和累，但是写完以后，再回过头来看的时候， 发现心中会有一种成就感由心而起，也希望可以帮助到大家一点点，可以关注我的微信公众号Rayson_666（Rayson开发分享）， 分享我学习和总结的经验给大家，并一起学习进步。
