Spring boot集成Swagger2，並配置多個掃描路徑，添加swagger-ui-layer

本文轉載自查看原文 2019-05-21 17:21 4101 springboot

Spring boot集成Swagger，並配置多個掃描路徑

1：認識Swagger

Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。

作用：

1. 接口的文檔在線自動生成。

2. 功能測試。

Swagger是一組開源項目，其中主要要項目如下：

Swagger-tools:提供各種與Swagger進行集成和交互的工具。例如模式檢驗、Swagger 1.2文檔轉換成Swagger 2.0文檔等功能。
Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架進行集成。
Swagger-js: 用於JavaScript的Swagger實現。
Swagger-node-express: Swagger模塊，用於node.js的Express web應用框架。
Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以為Swagger兼容API動態生成優雅文檔。
Swagger-codegen：一個模板驅動引擎，通過分析用戶Swagger資源聲明以各種語言生成客戶端代碼。

2：spring boot 集成 swagger

2.1 引入POM

        <!-- swagger2  -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.caspar-chen</groupId>
            <artifactId>swagger-ui-layer</artifactId>
            <version>1.1.3</version>
        </dependency>

2.2 配置swagger

在Application.java同級或子包中創建SwaggerConfig.java

package com.example.demo.swagger;

import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 創建API應用
     * apiInfo() 增加API相關信息
     * 通過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現，
     * 本例采用指定掃描的包路徑來定義指定要建立API的目錄。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 創建該API的基本信息（這些基本信息會展現在文檔頁面中）
     * 訪問地址：http://項目實際地址/swagger-ui.html
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("測試 APIs")
                .description("測試api接口文檔")
                .termsOfServiceUrl("http://www.baidu.com")
                .version("1.0")
                .build();
    }
}

2.3 添加文檔內容

在完成了上述配置后，其實已經可以生產文檔內容，我們訪問http://localhost:8080/swagger-ui.html。如圖

1539140458684.png

但是這樣的文檔主要針對請求本身，描述的主要來源是函數的命名，對用戶並不友好，我們通常需要自己增加一些說明來豐富文檔內容。

Swagger使用的注解及其說明：

@Api：用在類上，說明該類的作用。

@ApiOperation：注解來給API增加方法說明。

@ApiImplicitParams : 用在方法上包含一組參數說明。

@ApiImplicitParam：用來注解來給方法入參增加說明。

@ApiResponses：用於表示一組響應

@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息

l code：數字，例如400

l message：信息，例如"請求參數沒填好"

l response：拋出異常的類

@ApiModel：描述一個Model的信息（一般用在請求參數無法使用@ApiImplicitParam注解進行描述的時候）

l @ApiModelProperty：描述一個model的屬性

例如：

package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/user")
@Api(tags="用戶系統-用戶管理")
public class UserController {


    @Autowired
    private UserService userService;


    @GetMapping("updateMoblie")
    @ApiOperation(value="更新手機號", notes = "更新手機號接口")
    public String updateMoblie(Long userId){
        userService.updateMobile(userId);
        return "success";
    }

}

結果如圖

1539140725037.png

以上我們完成了spring boot與swagger的集成，但是使用springfox中的 RequestHandlerSelectors.basePackage("com.xxx") 只能支持單個包路徑的掃描匹配,如果我們業務中分了多個包，swagger怎么能掃描到呢？

3： swagger 多包掃描配置

要解決這個問題，我們可以參考一下RequestHandlerSelectors.basePackage的源碼

public class RequestHandlerSelectors {
  private RequestHandlerSelectors() {
    throw new UnsupportedOperationException();
  }

  /**
   * Any RequestHandler satisfies this condition
   *
   * @return predicate that is always true
   */
  public static Predicate<RequestHandler> any() {
    return Predicates.alwaysTrue();
  }

  /**
   * No RequestHandler satisfies this condition
   *
   * @return predicate that is always false
   */
  public static Predicate<RequestHandler> none() {
    return Predicates.alwaysFalse();
  }

  /**
   * Predicate that matches RequestHandler with handlers methods annotated with given annotation
   *
   * @param annotation - annotation to check
   * @return this
   */
  public static Predicate<RequestHandler> withMethodAnnotation(final Class<? extends Annotation> annotation) {
    return new Predicate<RequestHandler>() {
      @Override
      public boolean apply(RequestHandler input) {
        return input.isAnnotatedWith(annotation);
      }
    };
  }

  /**
   * Predicate that matches RequestHandler with given annotation on the declaring class of the handler method
   *
   * @param annotation - annotation to check
   * @return this
   */
  public static Predicate<RequestHandler> withClassAnnotation(final Class<? extends Annotation> annotation) {
    return new Predicate<RequestHandler>() {
      @Override
      public boolean apply(RequestHandler input) {
        return declaringClass(input).transform(annotationPresent(annotation)).or(false);
      }
    };
  }

  private static Function<Class<?>, Boolean> annotationPresent(final Class<? extends Annotation> annotation) {
    return new Function<Class<?>, Boolean>() {
      @Override
      public Boolean apply(Class<?> input) {
        return input.isAnnotationPresent(annotation);
      }
    };
  }


  private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
    return new Function<Class<?>, Boolean>() {
      @Override
      public Boolean apply(Class<?> input) {
        return ClassUtils.getPackageName(input).startsWith(basePackage);
      }
    };
  }

  /**
   * Predicate 匹配RequestHandler，並為處理程序方法的類提供基本包名.
   * predicate 包括與所提供的basePackage匹配的所有請求處理程序
   *
   * @param basePackage - base package of the classes
   * @return this
   */
  public static Predicate<RequestHandler> basePackage(final String basePackage) {
    return new Predicate<RequestHandler>() {
      @Override
      public boolean apply(RequestHandler input) {
        return declaringClass(input).transform(handlerPackage(basePackage)).or(true);
      }
    };
  }

  private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
    return Optional.fromNullable(input.declaringClass());
  }

}

我們看到 swagger 是通過Predicate 的apply 方法的返回值來判斷是非匹配的我們可以通過改造basePackage方法來實現多包掃描，改造 SwaggerConfig 如下

package com.hzcominfo.sinopec.pos;

import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {

    // 定義分隔符
    private static final String splitor = ";";

    /**
     * 創建API應用
     * api() 增加API相關信息
     * 通過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現，
     * 本例采用指定掃描的包路徑來定義指定要建立API的目錄。
     *
     * @return
     */
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(basePackage("com.hzcominfo.sinopec.pos.web.controller.mobilev1"
                        + splitor
                        + "com.hzcominfo.sinopec.pos.web.controller.mobilev2.api"))
                .paths(PathSelectors.any())
                .build();
    }

    //構建 api文檔的詳細信息函數,注意這里的注解引用的是哪個
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面標題
                .title("XXX項目接口")
                //創建人
                .contact(new Contact("userName", "", "linzp@hzcominfo.com"))
                //版本號
                .version("1.0.0-SNAPSHOT")
                //描述
                .description("")
                .build();
    }


    public static Predicate<RequestHandler> basePackage(final String basePackage) {
        return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
    }

    private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
        return input -> {
            // 循環判斷匹配
            for (String strPackage : basePackage.split(splitor)) {
                boolean isMatch = input.getPackage().getName().startsWith(strPackage);
                if (isMatch) {
                    return true;
                }
            }
            return false;
        };
    }

    private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
        return Optional.fromNullable(input.declaringClass());
    }


    /**
     * swagger2原始ui
     * http://localhost:8080/swagger-ui.html
     *
     * swagger-ui-layer訪問ui
     * http://localhost:8080/docs.html
     */
}

swagger2：

swagger-ui-layer：

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 Spring boot集成Swagger，並配置多個掃描路徑 Spring boot集成Swagger，並配置多個掃描路徑 SpringBoot集成Swagger2並配置多個包路徑掃描 spring boot集成Swagger2 Spring Boot 集成 Swagger2 與配置 OAuth2.0 授權 Spring Boot實戰：集成Swagger2 Spring Boot 入門（七）：集成 swagger2 Spring Boot 集成 Swagger2 教程 Spring Boot 2 Swagger2 Spring Boot啟用Swagger2