SpringBoot項目實戰(zhàn)（二十三篇）：整合Swagger2構(gòu)建強大的Restful Api接口文檔（三）

作者：方雷
個人博客：http://blog.chargingbunk.cn/
微信公眾號：rayson_666(Rayson開發(fā)分享)
個人專研技術(shù)方向：

  • 微服務(wù)方向：springboot, springCloud, Dubbo
  • 分布式/高并發(fā)： 分布式鎖， 消息隊列RabbitMQ
  • 大數(shù)據(jù)處理： Hadoop, spark, HBase等
  • python方向： python web開發(fā)

喜歡的朋友們可以關(guān)注我的簡書或微信公眾號(rayson_666), 一起交流學習， 后期會不斷更新有經(jīng)驗的干貨.

一， 前言

原生的swagger-ui并不是很美觀， 而且項目中如果出現(xiàn)了大量的api接口， 也不方便查看和調(diào)試。那么，這篇主要是說一下swagger-ui的界面優(yōu)化這個事，來漲漲見識。


image.png

所以接下來我將介紹兩款開源的Swagger-ui庫，配置也很簡單：

  • swagger-bootstrap-ui
  • swagger-ui-layer

二，整合swagger-bootstrap-ui

swagger-bootstrap-ui是基于swagger接口api實現(xiàn)的一套UI,因swagger原生ui是上下結(jié)構(gòu)的，在瀏覽接口時不是很清晰,所以，swagger-bootstrap-ui是基于左右菜單風格的方式,適用與我們在開發(fā)后臺系統(tǒng)左右結(jié)構(gòu)這種風格類似,方便與接口瀏覽
Github地址:https://github.com/xiaoymin/Swagger-Bootstrap-UI

1.首先來看看效果圖：

來自網(wǎng)絡(luò).png

如上圖， 接口文檔就成了左右結(jié)構(gòu)，如果感興趣可以繼續(xù)往下看，如何搭建的額。

2.將jar引入到pom文件中


    <!-- 構(gòu)建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項目實戰(zhàn)（二十三篇）：整合Swagger2構(gòu)建強大的Restful Api接口文檔（二）第二篇中的方式進行操作的話， 直接訪問同樣會出現(xiàn)Whitelabel Error Page的結(jié)果。如果不是，請忽略。

所以我們需要對webConfig類進行一個小小的完善，將 swagger-ui.html 替換成 /**，就可以映射所有的地址到該資源路徑下查找。

/**
     * 此方法是用來添加靜態(tài)資源映射的
     * 發(fā)現(xiàn)如果繼承了WebMvcConfigurationSupport，則在yml中配置的相關(guān)內(nèi)容會失效。 需要重新指定靜態(tài)資源
     */
    @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，觀察結(jié)果

image.png

里面具體的如何操作， 可以自己擴展一下，查閱資料。

三，整合swagger-ui-layer

swagger-ui-layer是基于swagger接口api實現(xiàn)的一套基于layer的UI,因swagger原生ui是上下結(jié)構(gòu)的，在瀏覽接口時不是很清晰,所以，swagger-ui-layer是基于左右菜單風格的方式,適用與我們在開發(fā)后臺系統(tǒng)左右結(jié)構(gòu)這種風格類似,方便與接口瀏覽
Github地址:https://github.com/caspar-chen/swagger-ui-layer
我偶然發(fā)現(xiàn)有另外一個作者在上面原作者的基礎(chǔ)上有優(yōu)化一些功能，我就引用的這一位作者的
他的Github的地址：https://github.com/ohcomeyes/swagger-ui-layer

1.首先來看看效果圖：

image.png

如上圖， 接口文檔就成了左右結(jié)構(gòu)，如果感興趣可以繼續(xù)往下看，如何搭建的額。

2.將jar引入到pom文件中


    <!-- 構(gòu)建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項目實戰(zhàn)（二十三篇）：整合Swagger2構(gòu)建強大的Restful Api接口文檔（二）第二篇中的方式進行操作的話， 直接訪問同樣會出現(xiàn)Whitelabel Error Page的結(jié)果。如果不是，請忽略。

所以我們需要對webConfig類進行一個小小的完善，將 swagger-ui.html 替換成 /**，就可以映射所有的地址到該資源路徑下查找。

/**
     * 此方法是用來添加靜態(tài)資源映射的
     * 發(fā)現(xiàn)如果繼承了WebMvcConfigurationSupport，則在yml中配置的相關(guān)內(nèi)容會失效。 需要重新指定靜態(tài)資源
     */
    @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，觀察結(jié)果

image.png

what?出現(xiàn)了白板， 也沒有什么顯示出來， 難道是不兼容問題。為啥上一個沒有出現(xiàn)問題， 而這一個出現(xiàn)了問題。

我對比了swagger-ui與swagger-ui-layer的文檔訪問，來看看有什么不同呢？
swagger-ui訪問正常的


swagger-ui.png

swagger-ui-layer訪問異常的


swagger-ui-layer.png

通過對比這兩個請求，可以發(fā)現(xiàn)swagger-ui-layer在請求/api-docs地址上少
了group這個參數(shù)。

而這個group參數(shù)不就是我們在Swagger2中配置的

/**
 * 
 * Swagger2配置類
 * @author 方雷(Rayson)
 * @微信公眾號: rayson_666(Rayson開發(fā)分享) 、
 * 分享springBoot springCloud技術(shù), 以及python,大數(shù)據(jù)學習系列
 * @個人博客: http://blog.chargingbunk.cn/
 * @簡書: http://www.itdecent.cn/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();
    }
    
    // 預(yù)覽地址:swagger-ui.html
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("利用swagger構(gòu)建測試系統(tǒng)api文檔")
                .description("接口訪問地址：http://localhost:8080/, by 方雷")
                .termsOfServiceUrl("http://localhost:8080/")
                //.contact("方雷")
                .version("1.0")
                .build();
    }
}

defaultApi()方法中有個groupName的配置， 而網(wǎng)上很多教程基本上都有配置這個參數(shù)，就給我們大家造成了誤解，開始思考：那是否可以刪除，默認沒有呢？答案是可以不用配置。那么接下來我們刪除一下，看是否可以成功。

刪除后的代碼如下：

/**
 * 
 * Swagger2配置類
 * @author 方雷(Rayson)
 * @微信公眾號: rayson_666(Rayson開發(fā)分享) 、
 * 分享springBoot springCloud技術(shù), 以及python,大數(shù)據(jù)學習系列
 * @個人博客: http://blog.chargingbunk.cn/
 * @簡書: http://www.itdecent.cn/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();
    }
    }
    
    // 預(yù)覽地址:swagger-ui.html
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("利用swagger構(gòu)建測試系統(tǒng)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類似， 可以自己擴展一下，查閱資料。

四，總結(jié)

SpringBoot整合Swagger也基本完成了，我花了一個下午時間，實踐加寫文章記錄，還是比較辛苦和累，但是寫完以后，再回過頭來看的時候， 發(fā)現(xiàn)心中會有一種成就感由心而起，也希望可以幫助到大家一點點，可以關(guān)注我的微信公眾號Rayson_666（Rayson開發(fā)分享）， 分享我學習和總結(jié)的經(jīng)驗給大家，并一起學習進步。

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容