第一章 SpringBoot快速开发框架 - 集成Swagger，生成API文档

作者简介：
🌹 作者：暗夜91
🤟 个人主页：暗夜91的主页
📝 如果感觉文章写的还有点帮助，请帮忙点个关注，我会持续输出高质量技术博文。

---

专栏文章:
1、集成Swagger，生成API文档
2、Mysql数据源配置
3、集成Redis
4、Spring Security + JWT实现登录权限认证
5、跨域配置

专栏源码：
针对该专栏功能，对源码进行整理，可以直接下载运行。
源码下载请移步：SpringBoot快速开发框架

---

一、集成Swagger，生成API文档

在前后端分离的项目中，API文档是非常必要的，一个优秀的API文档能够减少前后端开发人员大量的沟通时间，提高开发效率，因此能够提供优秀的API文档也是一个后端开发人员必备的素质。

目前能够生成API的工具有很多，我们这里使用Swagger作为生成API的工具。Swagger提供了完整的管理、测试和使用API的功能，其实时性对前后端都十分的友好。

1、集成方法 （1）引入依赖

在pom.xml文件中添加Swagger依赖

<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.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

（2）在application.yml中配置Swagger是否可用

swagger:
  enable: true

注：

Swagger提供对外接口，所以应该只用于开发测试环境，以上配置在生产环境中应设置为false

（3）在工程中添加Swagger配置文件

package com.lll.framework.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

/**
 * @author Liu Lili
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Value("${swagger.enable}")
    private boolean enableSwagger;

    /**
     * 构建api文档的详细信息函数
     * @return
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("RESTful API")
                .version("1.0")
                .description("API 描述")
                .build();
    }

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(enableSwagger).select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();

    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

2、Swagger配置说明 （1）Swagger扫描注解方法

Swagger扫描注解有两种不同的方式，具体如下：

1、指定包扫描方式

.apis(RequestHandlerSelectors.basePackage("com.lll.framework.module"))

该方式会扫描指定包下面所有的controller，不管是否使用了@Api注解。

2、扫描注解方式

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

该方式会扫描整个工程中所有使用了@Api注解的类和@ApiOperation注解的方法，上面的示例代码就是使用了该方式。

（2）指定包扫描方式扩展

指定包扫描方式有一定的局限，如果我们的controller并没有在一个统一的包中，或者对某些controller并不想暴露出去，这个时候直接使用扫描包的方式就无法实现了。

为了满足上面的需求，我们需要对包扫描方式进行改造，改造方式为重写basePackage方法，让basePackage方法支持多包路径扫描，具体实现如下：

    /**
     * 重写basePackage方法，使能够实现多包访问
     * @return com.google.common.base.Predicate
     */
    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());
    }

（3）对swagger中的请求添加全局参数

在实际开发中，后端对外提供的接口应该是有权限验证的，需要提供token验证请求的合法性，为了能够在Swagger中对接口进行测试工作，需要给所有的接口添加全局token参数，具体实现如下：

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(enableSwagger).select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(getParam());
    }

private List<Parameter> getParam(){
        ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        /**
         * Token 以及Authorization 为自定义的参数，session保存的名字是哪个就可以写成那个
         * header中的ticket参数非必填，传空也可以
         */
        ticketPar.name("Authorization").description("user ticket")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(true).build();
        pars.add(ticketPar.build());
        return pars;
    }

3、Swagger常用注解 （1）在Controller上注解

//1.在类上应用的注解:

@Api(tags = “这是一个控制器类”)

//2.在具体请求方法上的注解:

@ApiOperation(value = “功能总述” , notes = “具体描述”)

@ApiParam(value = “请求参数说明”)

（2）在实体类上的注解

//1.在类上应用的注解:

@ApiModel(description = “XX实体类”)

//2.在实体类属性上应用的注解:

@ApiModelProperty(value = “属性说明”)