springboot集成swagger2，初级入门一文足矣

最近项目需要提供api文档给测试及需求，网上文章很多，其实挺简单的。但是注解不是很适合我，所以我又整理了一版。

其中代码参考了很多网上的文章，但是也找不到具体的链接了。我只是做了整合和备注。如果有需要，可以私聊我加上出处。谢谢理解

直接上代码，看注解1、2、3、4基本就可以直接运行起来。

import com.google.common.base.Function;
import com.google.common.base.Optional;
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.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

import static com.google.common.collect.Lists.newArrayList;
import static springfox.documentation.builders.RequestHandlerSelectors.basePackage;

/**
 * Swagger 是一个规范和完整的框架，
 * 用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
 * 总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
 * 文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
 *
 * swagger集成：
 * 1.pom.xml导包
           <!-- swagger -->
           <dependency>
               <groupId>io.springfox</groupId>
               <artifactId>springfox-swagger2</artifactId>
               <version>2.7.0</version>
           </dependency>
           <!-- http://localhost:8080/swagger-ui.html UI展示 http://localhost:8080/v2/api-docs 无UI的描述API的swagger元数据json https://editor.swagger.io/ -->
           <dependency>
               <groupId>io.springfox</groupId>
               <artifactId>springfox-swagger-ui</artifactId>
               <version>3.0.0</version>
           </dependency>
           <!-- http://localhost:8080/doc.html 国人开发的增强UI<https://www.xiaominfo.com/> -->
           <dependency>
               <groupId>com.github.xiaoymin</groupId>
               <artifactId>swagger-bootstrap-ui</artifactId>
               <version>1.9.6</version>
           </dependency>
 *
 * 2.SwaggerConfig.java
        @ EnableSwagger2支持Swagger 2的SpringFox支持。
        DocumentationType.SWAGGER_2告诉Docket bean我们正在使用Swagger规范的版本2。
        select（）创建一个构建器，用于定义哪些控制器及其生成的文档中应包含哪些方法。
        apis（）定义要包含的类（控制器和模型类）。这里我们包括所有这些，但您可以通过基础包，类注释等来限制它们。
        paths（）允许您根据路径映射定义应包含哪个控制器的方法。我们现在包括所有这些，但您可以使用正则表达式等限制它。
 *
 * 3.Controller加注解
 *      常用注解：
           3.1类名级别：
               @Api(value = "用户相关", tags = "用户相关")
               或者
               @ApiIgnore//swagger页面不扫描此Controller
           3.2方法级别
               @ApiOperation(value = "获取群组的用户", notes = "获取群组的用户notes")
               @ApiImplicitParams({
                       @ApiImplicitParam(name = "chatId", value = "userId/groupId", required = true, paramType = "query"),
                       @ApiImplicitParam(name = "loginAid", value = "登录用户Id", required = true, paramType = "query", dataType = "String")
               })
 * 4.Vo加注解
        @ApiModelProperty(value = "手机号", example = "13000000000", required = true)
        private String mobile;
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置文件添加是否允许展示swagger页面，上线时一定要改为false
    @Value("${swagger.show}")
    private boolean flag;
    // 定义分隔符
    private static final String splitor = ";";

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(flag)
                .apiInfo(apiInfo())
                .select()
                //.apis(RequestHandlerSelectors.any())              //扫描所有包
                //.apis(basePackage("com.guoyin.im.controller.im"+splitor+"com.guoyin.im.controller.system"))   //自定义扫描
                .apis(basePackage("com.guoyin.im.controller.im"))   //自定义扫描
                .paths(PathSelectors.any())
                .build()
                //.globalOperationParameters(globalOperation());      //每个接口调用都填写token
                .securitySchemes(security());                     //统一填写一次token
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("TQ项目API接口")
                .description("This is a restful api document of TQ")
                .version("1.0.0")
                .build();
    }

    //给每个方法添加固定参数
    private List<Parameter> globalOperation(){
        // 添加请求参数，我们这里把access_token作为请求头部参数传入后端
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<Parameter>();
        /**
         *  paramType：表示参数放在哪个地方
         *     header-->请求参数的获取：@RequestHeader(代码中接收注解)
         *     query-->请求参数的获取：@RequestParam(代码中接收注解)
         *     path（用于restful接口）-->请求参数的获取：@PathVariable(代码中接收注解)
         *     body-->请求参数的获取：@RequestBody(代码中接收注解)
         *     form（不常用）
         */
        parameterBuilder.name("access_token").description("token")
                .modelRef(new ModelRef("string")).parameterType("query").required(false).build();
        parameters.add(parameterBuilder.build());
        return parameters;
    }

    //所有方法统一传递固定参数
    private List<ApiKey> security() {
        return newArrayList(
                new ApiKey("token", "access_token", "query")
        );
    }

    //自定义扫描多个路径
    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());
    }
}