SpringBoot系列——集成Swagger2

 

1. pom.xml

   
   
       io.springfox
       springfox-swagger2
       2.8.0
   
   
       io.springfox
       springfox-swagger-ui
       2.8.0
   

    

2. application.yml

   ## 7. swagger 配置
   swagger:
     api_title: swagger 配置
     api_version: 1.0
     author: hahashujia
     email: 有效邮箱
     url: 有效地址

    

3. Swagger2Config.java

   package com.hahashujia.config;
   
   import com.hahashujia.basic.annotation.ApiType;
   import com.google.common.base.Predicate;
   import org.springframework.beans.factory.annotation.Value;
   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.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   /**
    * 说明：
    * swagger2 配置类。
    * @author hahashujia
    */
   @Configuration
   @EnableSwagger2
   public class Swagger2Config {
   
   
       @Value("${swagger.api_title}")
       private String apiTitle;
       @Value("${swagger.api_version}")
       private String apiVersion;
       @Value("${swagger.author}")
       private String author;
       @Value("${swagger.email}")
       private String email;
       @Value("${swagger.url}")
       private String url;
   
       /**
        * 说明:
        * 1、确定Swageer2 Docket的分组类型；
        * 2、支持创建多个Docket Bean, 推荐以"业务模块"进行分组:
        * @return
        */
       @Bean
       public Docket createRestApi1() {
           return this.createDocket(BusinessGroup.OPEN_API);
       }
   
       @Bean
       public Docket createRestApi6() {
           return this.createDocket(BusinessGroup.OTHERS);
       }
   
       @Bean
       public Docket createRestApi8() {
           return this.createDocket(BusinessGroup.BANK_STATEMENT);
       }
   
   
       /** 文档对象 */
       private Docket createDocket(String apiTypeValue) {
   
           return new Docket(DocumentationType.SWAGGER_2)
                   .groupName(apiTypeValue)
                   .apiInfo(this.apiInfo(apiTypeValue))
                   .select()
                   .apis(this.createPredicate(apiTypeValue))
                   .paths(PathSelectors.any())
                   .build();
       }
   
   
       /**
        * 确定API meta信息。
        * @return
        */
       private ApiInfo apiInfo(String apiTypeValue) {
           return new ApiInfoBuilder()
                   .title(this.apiTitle + ":: " + apiTypeValue.substring(2))
                   .version(this.apiVersion)
                   .build();
       }
   
   
       /**
        * 说明:
        * 根据参数值来生成predicate实例。
        *
        * 备注:
        * 1、运行时，当请求处理类的@ApiType 的 apiTypeValue与参数值相等则返回true, 否则返回false;
        * 2、对于没有使用@ApiType 且 入参为@see BusinessGroup.OTHERS的，也返回true；对其存放到缺省的类别。
        *
        * @param apiTypeValue
        * @return
        */
       private Predicate createPredicate(String apiTypeValue) {
   
           Predicate predicate = (RequestHandler requestHandler) -> {
   
               // 1. 判断注解是否存在:
               if ( requestHandler.findControllerAnnotation(ApiType.class).isPresent() ) {
                   // 1. 提取注解:
                   ApiType apiType = requestHandler.findControllerAnnotation(ApiType.class).get();
                   // 2. 提取注解的值:
                   if (apiType.apiTypeValue().equals(apiTypeValue)) {
                       return true;
                   }
               } else if ( BusinessGroup.OTHERS.equals(apiTypeValue) )  {
                   // 对于没有使用ApiType注解的，则放行（归档到"其它"组别）
                   return true;
               }
   
               return false;
           };
   
           return predicate;
       }
   
   
       /** 业务单元的定义 (使用序号进行Api显示排序)*/
       public static class BusinessGroup {
   
           public static final String BANK_STATEMENT = "1、swagger2 配置";
           public static final String OPEN_API = "2、Open-Api";
           public static final String OTHERS = "3、其它";
   
       }
   
   }
   

    

4. ApiType.java

   package com.hahashujia.basic.annotation;
   
   import java.lang.annotation.ElementType;
   import java.lang.annotation.Retention;
   import java.lang.annotation.RetentionPolicy;
   import java.lang.annotation.Target;
   
   /**
    * 说明：
    * API 归档注解。
    * @author hahashujia
    */
   @Target(ElementType.TYPE)
   @Retention(RetentionPolicy.RUNTIME)
   public @interface ApiType {
   
       String apiTypeValue() default "";
   
   }
   

    

5. 最后调用

   Controller类加注解
   
   @ApiType(apiTypeValue = Swagger2Config.BusinessGroup.BANK_STATEMENT)
   @Api(description = "swagger2 配置")
   
   Controller 方法注解
   
   @ApiOperation(value = "接口描述", notes = "接口描述")
   
   
   

    

6. 调用地址：http://localhost:8038/hahashujia/swagger-ui.html

7. 最后注意一点，配置完之后记得将浏览器缓存清空。不然容易出现空白页面

8. 注解示例
    

   1、方法
   @ApiOperation(value = "获取映射关系", notes = "参数(param) 由多个映射参数按照value+“,”+value ")
   @ApiImplicitParams({
       @ApiImplicitParam(value = "是否全量", name = "fullAmount", required = true, paramType = "query", dataType = "boolean", defaultValue = "false"),
       @ApiImplicitParam(value = "结构编码", name = "structureCode", required = true, paramType = "query", dataType = "String")
   })
   
   2、类
   @Api("外部系统接口")