引入 swagger 依賴關(guān)系

<!--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"})// 設(shè)置 dev test 環(huán)境開啟
public class SwaggerConfig {
    @Bean
    public Docket controllerApi() {
        //添加head參數(shù)start
        ParameterBuilder signPar = new ParameterBuilder();
        ParameterBuilder RTimePar = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<>();
        signPar.name("sign").description("簽名：請(qǐng)求參數(shù)名字母升序md5加密").modelRef(new ModelRef("string")).parameterType("header").required(true).build();
        RTimePar.name("time").description("請(qǐng)求時(shí)間戳").modelRef(new ModelRef("string")).parameterType("header").required(true).build();

        parameters.add(signPar.build());
        parameters.add(RTimePar.build());
        //添加head參數(shù)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

整合時(shí)遇到的問題

1. 后臺(tái)報(bào)錯(cuò)

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'

我們看一下錯(cuò)誤信息，No mapping found for HTTP request with URI [/swagger-ui.html] 沒有前端資源的映射。發(fā)現(xiàn)是靜態(tài)文件資源映射問題。

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

3.png

spring boot 自動(dòng)配置并沒有將 swagger 的靜態(tài)資源路徑映射到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

這個(gè)問題就比較神奇了。百度之后發(fā)現(xiàn)各種回答。大多跟攔截器，資源映射等等有關(guān)。但是我的項(xiàng)目這些問題都排除了。

此時(shí)我突然發(fā)現(xiàn)了這個(gè)問題出現(xiàn)的規(guī)律：
正好當(dāng)時(shí)項(xiàng)目我要部署，測試服務(wù)器，一些配置信息需要修改。所以我采取了多配置文件的方式。重新創(chuàng)建了一個(gè)application-demo.yml配置文件并將測試服務(wù)器的配置內(nèi)容修改完成。在application.yml主配置文件內(nèi)將 spring.profiles.active=dev 修改為spring.profiles.active=demo

此時(shí)啟動(dòng)項(xiàng)目。訪問swagger.html開始 不停彈窗。
我再將demo 修改回 dev 之后。訪問swagger.html 就又好了。

此時(shí)我就突然想到了。SwaggerConfig 配置文件內(nèi)的
@Profile({"dev", "test"})// 設(shè)置 dev test 環(huán)境開啟
指定dev test 環(huán)境開啟 swagger api

修改 @Profile({"dev", "test","demo"})// 設(shè)置 dev test demo環(huán)境開啟

重新啟動(dòng)項(xiàng)目，修改成功。