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

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

1：認識Swagger

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

作用：

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

​ 2. 功能測試。

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

1. Swagger-tools:提供各種與Swagger進行集成和交互的工具。例如模式檢驗、Swagger 1.2文檔轉換成Swagger 2.0文檔等功能。

2. Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架進行集成。

3. Swagger-js: 用於JavaScript的Swagger實現。

4. Swagger-node-express: Swagger模塊，用於node.js的Express web應用框架。

5. Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以為Swagger兼容API動態生成優雅文檔。

6. Swagger-codegen：一個模板驅動引擎，通過分析用戶Swagger資源聲明以各種語言生成客戶端代碼。

2：spring boot 集成 swagger

2.1 引入POM

 <!-- swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</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 {
<span class="token comment"><span class="hljs-comment">/**
 * 創建API應用
 * apiInfo() 增加API相關信息
 * 通過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現，
 * 本例采用指定掃描的包路徑來定義指定要建立API的目錄。
 *
 * <span class="hljs-doctag">@return</span>
 */</span></span>
<span class="token annotation punctuation"><span class="hljs-meta">@Bean</span></span>
<span class="token keyword"><span class="hljs-function"><span class="hljs-keyword">public</span></span></span><span class="hljs-function"> </span><span class="token class-name"><span class="hljs-function">Docket</span></span><span class="hljs-function"> </span><span class="token function"><span class="hljs-function"><span class="hljs-title">createRestApi</span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params">(</span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params">)</span></span></span><span class="hljs-function"> </span><span class="token punctuation">{</span>
    <span class="token keyword"><span class="hljs-keyword">return</span></span> <span class="token keyword"><span class="hljs-keyword">new</span></span> <span class="token class-name">Docket</span><span class="token punctuation">(</span><span class="token class-name">DocumentationType</span><span class="token punctuation">.</span>SWAGGER_2<span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">apiInfo</span><span class="token punctuation">(</span><span class="token function">apiInfo</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">apis</span><span class="token punctuation">(</span><span class="token class-name">RequestHandlerSelectors</span><span class="token punctuation">.</span><span class="token function">basePackage</span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string">"com.example.demo.controller"</span></span><span class="token punctuation">)</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">paths</span><span class="token punctuation">(</span><span class="token class-name">PathSelectors</span><span class="token punctuation">.</span><span class="token function">any</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">build</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

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

}

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 {
<span class="token annotation punctuation"><span class="hljs-meta">@Autowired</span></span>
<span class="token keyword"><span class="hljs-keyword">private</span></span> <span class="token class-name">UserService</span> userService<span class="token punctuation">;</span>


<span class="token annotation punctuation"><span class="hljs-meta">@GetMapping</span></span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string">"updateMoblie"</span></span><span class="token punctuation">)</span>
<span class="token annotation punctuation"><span class="hljs-meta">@ApiOperation</span></span><span class="token punctuation">(</span>value<span class="token operator">=</span><span class="token string"><span class="hljs-string">"更新手機號"</span></span><span class="token punctuation">,</span> notes <span class="token operator">=</span> <span class="token string"><span class="hljs-string">"更新手機號接口"</span></span><span class="token punctuation">)</span>
<span class="token keyword"><span class="hljs-function"><span class="hljs-keyword">public</span></span></span><span class="hljs-function"> </span><span class="token class-name"><span class="hljs-function">String</span></span><span class="hljs-function"> </span><span class="token function"><span class="hljs-function"><span class="hljs-title">updateMoblie</span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params">(</span></span></span><span class="token class-name"><span class="hljs-function"><span class="hljs-params">Long</span></span></span><span class="hljs-function"><span class="hljs-params"> userId</span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params">)</span></span></span><span class="token punctuation">{</span>
    userService<span class="token punctuation">.</span><span class="token function">updateMobile</span><span class="token punctuation">(</span>userId<span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token keyword"><span class="hljs-keyword">return</span></span> <span class="token string"><span class="hljs-string">"success"</span></span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

}

結果如圖

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.example.demo.swagger;
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.builders.RequestHandlerSelectors;
 import springfox.documentation.service.ApiInfo;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
 @EnableSwagger2
 public class SwaggerConfig {
<span class="token comment"><span class="hljs-comment">// 定義分隔符</span></span>
<span class="token keyword"><span class="hljs-keyword">private</span></span> <span class="token keyword"><span class="hljs-keyword">static</span></span> <span class="token keyword"><span class="hljs-keyword">final</span></span> <span class="token class-name">String</span> splitor <span class="token operator">=</span> <span class="token string"><span class="hljs-string">";"</span></span><span class="token punctuation">;</span>

<span class="token comment"><span class="hljs-comment">/**
 * 創建API應用
 * api() 增加API相關信息
 * 通過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現，
 * 本例采用指定掃描的包路徑來定義指定要建立API的目錄。
 *
 * <span class="hljs-doctag">@return</span>
 */</span></span>
<span class="token annotation punctuation"><span class="hljs-meta">@Bean</span></span>
<span class="token keyword"><span class="hljs-function"><span class="hljs-keyword">public</span></span></span><span class="hljs-function"> </span><span class="token class-name"><span class="hljs-function">Docket</span></span><span class="hljs-function"> </span><span class="token function"><span class="hljs-function"><span class="hljs-title">api</span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params">(</span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params">)</span></span></span><span class="hljs-function"> </span><span class="token punctuation">{</span>
    <span class="token keyword"><span class="hljs-keyword">return</span></span> <span class="token keyword"><span class="hljs-keyword">new</span></span> <span class="token class-name">Docket</span><span class="token punctuation">(</span><span class="token class-name">DocumentationType</span><span class="token punctuation">.</span>SWAGGER_2<span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">apiInfo</span><span class="token punctuation">(</span><span class="token function">apiInfo</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token punctuation">)</span>

.apis(basePackage("com.example.demo.controller"+splitor+"com.example.demo.test"))
 .paths(PathSelectors.any())
 .build();
 }
<span class="token comment"><span class="hljs-comment">/**
 * 構建 api文檔的詳細信息函數
 *
 * <span class="hljs-doctag">@return</span>
 */</span></span>
<span class="token keyword"><span class="hljs-function"><span class="hljs-keyword">private</span></span></span><span class="hljs-function"> </span><span class="token class-name"><span class="hljs-function">ApiInfo</span></span><span class="hljs-function"> </span><span class="token function"><span class="hljs-function"><span class="hljs-title">apiInfo</span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params">(</span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params">)</span></span></span><span class="hljs-function"> </span><span class="token punctuation">{</span>
    <span class="token keyword"><span class="hljs-keyword">return</span></span> <span class="token keyword"><span class="hljs-keyword">new</span></span> <span class="token class-name">ApiInfoBuilder</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">title</span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string">"測試 APIs"</span></span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">description</span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string">"測試api接口文檔"</span></span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">version</span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string">"1.0"</span></span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">build</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>


<span class="token keyword"><span class="hljs-function"><span class="hljs-keyword">public</span></span></span><span class="hljs-function"> </span><span class="token keyword"><span class="hljs-function"><span class="hljs-keyword">static</span></span></span><span class="hljs-function"> </span><span class="token class-name"><span class="hljs-function">Predicate</span></span><span class="token generics"><span class="token punctuation"><span class="hljs-function">&lt;</span></span><span class="token class-name"><span class="hljs-function">RequestHandler</span></span><span class="token punctuation"><span class="hljs-function">&gt;</span></span></span><span class="hljs-function"> </span><span class="token function"><span class="hljs-function"><span class="hljs-title">basePackage</span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params">(</span></span></span><span class="token keyword"><span class="hljs-function"><span class="hljs-params"><span class="hljs-keyword">final</span></span></span></span><span class="hljs-function"><span class="hljs-params"> </span></span><span class="token class-name"><span class="hljs-function"><span class="hljs-params">String</span></span></span><span class="hljs-function"><span class="hljs-params"> basePackage</span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params">)</span></span></span><span class="hljs-function"> </span><span class="token punctuation">{</span>
    <span class="token keyword"><span class="hljs-keyword">return</span></span> input <span class="token operator">-&gt;</span> <span class="token function">declaringClass</span><span class="token punctuation">(</span>input<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">transform</span><span class="token punctuation">(</span><span class="token function">handlerPackage</span><span class="token punctuation">(</span>basePackage<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">or</span><span class="token punctuation">(</span><span class="token boolean"><span class="hljs-keyword">true</span></span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

<span class="token keyword"><span class="hljs-keyword">private</span></span> <span class="token keyword"><span class="hljs-keyword">static</span></span> <span class="token class-name">Function</span><span class="token generics"><span class="token punctuation">&lt;</span><span class="token class-name">Class</span><span class="token punctuation">&lt;</span><span class="token operator">?</span><span class="token punctuation">&gt;</span><span class="token punctuation">,</span> <span class="token class-name">Boolean</span><span class="token punctuation">&gt;</span></span> <span class="token function">handlerPackage</span><span class="token punctuation">(</span><span class="token keyword"><span class="hljs-keyword">final</span></span> <span class="token class-name">String</span> basePackage<span class="token punctuation">)</span>     <span class="token punctuation">{</span>
    <span class="token keyword"><span class="hljs-keyword">return</span></span> input <span class="token operator">-&gt;</span> <span class="token punctuation">{</span>
        <span class="token comment"><span class="hljs-comment">// 循環判斷匹配</span></span>
        <span class="token keyword"><span class="hljs-keyword">for</span></span> <span class="token punctuation">(</span><span class="token class-name">String</span> strPackage <span class="token operator">:</span> basePackage<span class="token punctuation">.</span><span class="token function">split</span><span class="token punctuation">(</span>splitor<span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
            <span class="token keyword"><span class="hljs-keyword">boolean</span></span> isMatch <span class="token operator">=</span> input<span class="token punctuation">.</span><span class="token function">getPackage</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">getName</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">startsWith</span><span class="token punctuation">(</span>strPackage<span class="token punctuation">)</span><span class="token punctuation">;</span>
            <span class="token keyword"><span class="hljs-keyword">if</span></span> <span class="token punctuation">(</span>isMatch<span class="token punctuation">)</span> <span class="token punctuation">{</span>
                <span class="token keyword"><span class="hljs-keyword">return</span></span> <span class="token boolean"><span class="hljs-keyword">true</span></span><span class="token punctuation">;</span>
            <span class="token punctuation">}</span>
        <span class="token punctuation">}</span>
        <span class="token keyword"><span class="hljs-keyword">return</span></span> <span class="token boolean"><span class="hljs-keyword">false</span></span><span class="token punctuation">;</span>
    <span class="token punctuation">}</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

<span class="token keyword"><span class="hljs-keyword">private</span></span> <span class="token keyword"><span class="hljs-keyword">static</span></span> <span class="token class-name">Optional</span><span class="token generics"><span class="token punctuation">&lt;</span><span class="token operator">?</span> <span class="token keyword">extends</span> <span class="token class-name">Class</span><span class="token punctuation">&lt;</span><span class="token operator">?</span><span class="token punctuation">&gt;</span><span class="token punctuation">&gt;</span></span> <span class="token function">declaringClass</span><span class="token punctuation">(</span><span class="token class-name">RequestHandler</span> input<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token keyword"><span class="hljs-keyword">return</span></span> <span class="token class-name">Optional</span><span class="token punctuation">.</span><span class="token function">fromNullable</span><span class="token punctuation">(</span>input<span class="token punctuation">.</span><span class="token function">declaringClass</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>


<span class="token comment"><span class="hljs-comment">/**
 * http://localhost:8080/swagger-ui.html
 */</span></span>

}

通過以上配置 我們就可以掃描到 com.example.demo.controller 和 com.example.demo.test 兩個包下的接口信息了。

完！

原文地址：https://www.jianshu.com/p/dcaff30f91cc?tdsourcetag=s_pctim_aiomsg