SpringBoot整合swagger

如今Web項目先後端分離愈來愈多，先後端的溝通成本成了頭大的難題。

上個項目雖然使用Postman已經下降了很多溝通成本，可是仍是要手寫很多Api到Postman測試，耗費了很多時間。此次新項目決定使用SpringBoot來作，各方面都節省了很多配置，一想到Api的對接就有點頭大，因而決定把Swagger集成進來，實現Api文檔的自動生成（經過http://localhost:8080/swagger-ui.html直接訪問），這樣先後端對接基本上就零成本了。

話很少說，搞起。

首先，pom引入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>

而後在Springboot的Appilication類同目錄下新建Swagger2.java。

Swagger2：

@Configuration
public class Swagger2 {

    //swagger2的配置文件，這裏能夠配置swagger2的一些基本的內容，好比掃描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //爲當前包路徑
                .apis(RequestHandlerSelectors.basePackage("com.deepinno.dojet.ims.jy.web"))
                .paths(PathSelectors.any())
                .build();
    }

    //構建 api文檔的詳細信息函數,注意這裏的註解引用的是哪一個
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面標題
                .title("瀟湘夜雨RESTful API")
                //建立人
                .contact(new Contact("瀟湘夜雨", "https://crazycrabs.top", "xtf2011@gmail.com"))
                //版本號
                .version("1.0")
                //描述
                .description("瀟湘夜雨API測試")
                .build();
    }

}

注意Swagger2中加入@Configuration註解，表示這是一個配置類。

Application類加上@EnableSwagger2註解，表示啓用Swagger。

 

此時已經能夠訪問http://localhost:8080/swagger-ui.html。

寫一個Controller來測試Swagger：

package com.deepinno.dojet.ims.jy.web;

import com.deepinno.dojet.ims.jy.model.user.UserInfo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/swagger")
@Api(value="/swagger", tags="測試接口模塊")
public class TestController {

    @ApiOperation(value="展現首頁信息value", notes = "展現首頁信息notes")
    @GetMapping("/show")
    public Object showInfo(){
        return "hello world";
    }

    @ApiOperation(value="添加用戶信息", notes = "添加用戶信息")
    @ApiImplicitParam(name="userInfo", value="UserInfo", required = true, dataType = "UserInfo")
    @PostMapping("/addUser")
    public Object addUser(@RequestBody UserInfo userInfo){
        return "success";
    }

}

訪問Swagger的UI，能夠看到已經生成了相應的API接口：

至此完成了對Swagger的集成，更多功能只需對照文檔便可實現。

 

可能會出現的問題處理：

若是項目已經配置了Shiro，訪問會被Shiro攔截，修改Shiro的過濾器便可解決：

filterChainDefinitionMap.put("/swagger-ui.html", "anon");
filterChainDefinitionMap.put("/webjars/**", "anon");
filterChainDefinitionMap.put("/v2/**", "anon");
filterChainDefinitionMap.put("/swagger-resources/**", "anon");

 

若是訪問Swagger UI顯示404。多是配置了自定義的WebMvcConfiguration（好比爲了配置fastjson轉換器），繼承了WebMvcConfigurationSupport，而繼承WebMvcConfigurationSupport的狀況下，Springboot的默認靜態資源過濾器就失效了，因而須要配置一下過濾器：

/**
     * 發現若是繼承了WebMvcConfigurationSupport，則在yml中配置的相關內容會失效。
     * 須要從新指定靜態資源
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }


    /**
     * 配置servlet處理
     */
    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }

 這樣便可正常訪問Swagger的UI。