我爱编程

SpringBoot项目实战（二十三篇）：整合Swagger2构

2018-06-09  本文已影响153人  raysonfang

作者：方雷
个人博客：http://blog.chargingbunk.cn/
微信公众号：rayson_666(Rayson开发分享)
个人专研技术方向：

  • 微服务方向：springboot, springCloud, Dubbo
  • 分布式/高并发： 分布式锁， 消息队列RabbitMQ
  • 大数据处理： Hadoop, spark, HBase等
  • python方向： python web开发

喜欢的朋友们可以关注我的简书或微信公众号(rayson_666), 一起交流学习， 后期会不断更新有经验的干货.

一， 前言

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


image.png

所以接下来我将介绍两款开源的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.首先来看看效果图：

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

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，观察结果

image.png

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

三，整合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.首先来看看效果图：

image.png

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

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，观察结果

image.png

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

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


swagger-ui.png

swagger-ui-layer访问异常的


swagger-ui-layer.png

通过对比这两个请求，可以发现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

image.png

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

四，总结

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

上一篇下一篇

猜你喜欢

热点阅读