Springboot + Swagger使用心得

笔者这两天由于接口测试需要，给自己的项目添加了一下swagger，中间也碰到了一些问题，在这里记录一下。

---

一、使用swagger之前必须添加的依赖

<!-- 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>

二、创建一个swagger配置文件

package com.muyichen.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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.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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 这是种对象可以创建多个，然后在swagger-ui的下拉框里会出现多个模块
     * @return
     */
    @Bean
    public Docket createRestApi(){
        // 添加请求参数，这里把token作为请求头部参数传入后端
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<>();
        parameterBuilder.name("Authorization")
                        .description("令牌")
                        .modelRef(new ModelRef("string"))
                        .parameterType("header")
                        .required(false).build();
        parameters.add(parameterBuilder.build());
        return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())
                        .select()
                        // 默认扫描全路径
                        //.apis(RequestHandlerSelectors.any())
                        // 扫描指定路径 
                        .apis(RequestHandlerSelectors.basePackage("com.muyichen.demo"))
                        .paths(PathSelectors.any())
                        .build()
                        .globalOperationParameters(parameters);
    }

    /**
     * 公共配置信息，这些信息会显示在swagger-ui.html页面上
     * @return
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("D+ 视频上传 API")
                .description("This is a restful api document of Spring Boot.")
                .version("1.0")
                .build();
    }

}

一般来说完成上述两步就可以使用swagger了，具体的接口注解和参数注解，请参考官方文档，这里就不一一赘述了，下面主要介绍的是配置过程中，常见的一些问题（笔者遇到过的）。

三、使用过程中常见的一些问题

1、访问/swagger-ui.html时，控制台打印404（找不到页面）

原因：一般出这个问题都是由于重写了WebMvcConfigurationSupport类中的addResourceHandlers()方法，使得Spring找不到swagger模块的对应路径导致。

解决办法：在重写的addResourceHandlers()方法中添加上swagger模块静态资源的对应路径，如下图

@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/static/**")
            .addResourceLocations(ResourceUtils.CLASSPATH_URL_PREFIX + "/static/");
    registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations(ResourceUtils.CLASSPATH_URL_PREFIX + "/META-INF/resources/");
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations(ResourceUtils.CLASSPATH_URL_PREFIX + "/META-INF/resources/webjars/");
    super.addResourceHandlers(registry);
}

引申一下那个静态资源文件配置路径

笔者之前在网上查询修复方案的时候，发现有许多的博文中静态资源路径都是这样写的
可是笔者这样配置后，发现我前端页面的静态资源文件（CSS，JS之类的）找不到了，之后笔者改了下配置，变成了这样：

然后页面静态资源文件就能找到了。当然具体情况具体分析，笔者的页面没有做前后端分离，html中的静态资源文件路径前都加了/static前缀，所以菜肴这样调整，如果没有这个前缀的话，之前的写法也行。

2、扫包路径最好配置一下

笔者没有配置骚包路径的时候，默认是全路径扫描，然后扫出来的接口中有一部分是某些jar包中自带的，会影响后期对整个业务逻辑的梳理。

3、如何分服务配置多模块接口

这点在代码的注释中有写到过，主要就是在swagger配置文件中创建一个新的Docket对象（记住加上@Bean注解，让其注入Spring容器中），这个对象中配置对应服务的扫包路径就好了。