springBoot 整合 swagger

引入 swagger 依赖关系

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

swagger 配置

@Configuration
@EnableSwagger2
@Profile({"dev", "test"})// 设置 dev test 环境开启
public class SwaggerConfig {
    @Bean
    public Docket controllerApi() {
        //添加head参数start
        ParameterBuilder signPar = new ParameterBuilder();
        ParameterBuilder RTimePar = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<>();
        signPar.name("sign").description("签名：请求参数名字母升序md5加密").modelRef(new ModelRef("string")).parameterType("header").required(true).build();
        RTimePar.name("time").description("请求时间戳").modelRef(new ModelRef("string")).parameterType("header").required(true).build();

        parameters.add(signPar.build());
        parameters.add(RTimePar.build());
        //添加head参数end

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("XXX")
                        .description("XXX")
                        .contact(new Contact("XXX", "XXX", "XXX@xx.xx"))
                        .version("1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))           //加了ApiOperation注解的方法，生成接口文档
                .paths(PathSelectors.any())
                .build().globalOperationParameters(parameters);
    }
}

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

@Api(value = "HOME", tags = "HOME")
@RestController
@RequestMapping("/home")
public class HomeController {

    @ApiOperation(value = "home", notes = "HOME",httpMethod = "GET")
    @GetMapping
    public String home(){
        return "home";
    }
}

swagger2 整合成功。
访问地址 http://localhost:8080/swagger-ui.html

1.png

整合时遇到的问题

1. 后台报错

2018-07-26 11:25:55.375  WARN 15601 --- [nio-8080-exec-8] o.s.web.servlet.PageNotFound             : No mapping found for HTTP request with URI [/swagger-ui.html] in DispatcherServlet with name 'dispatcherServlet'

我们看一下错误信息，No mapping found for HTTP request with URI [/swagger-ui.html] 没有前端资源的映射。发现是静态文件资源映射问题。

swagger 所有的前端文件都在springfox-swagger-ui.jar 文件里。目录如下：

3.png

spring boot 自动配置并没有将 swagger 的静态资源路径映射到META-INF/resources/ 下面。我们需要自己增加映射。

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

2. 页面不停弹出窗口。

   
   2.png

这个问题就比较神奇了。百度之后发现各种回答。大多跟拦截器，资源映射等等有关。但是我的项目这些问题都排除了。

此时我突然发现了这个问题出现的规律：
正好当时项目我要部署，测试服务器，一些配置信息需要修改。所以我采取了多配置文件的方式。重新创建了一个application-demo.yml配置文件并将测试服务器的配置内容修改完成。在application.yml主配置文件内将 spring.profiles.active=dev 修改为spring.profiles.active=demo

此时启动项目。访问swagger.html开始 不停弹窗。
我再将demo 修改回 dev 之后。访问swagger.html 就又好了。

此时我就突然想到了。SwaggerConfig 配置文件内的
@Profile({"dev", "test"})// 设置 dev test 环境开启
指定dev test 环境开启 swagger api

修改 @Profile({"dev", "test","demo"})// 设置 dev test demo环境开启

重新启动项目，修改成功。