SSM三大框架整合Springfox(Swagger2)详细解决方案

由于项目中使用的是前后端分离，所以，频繁的需要进行数据的交互和接口的调用，所以需要api文档的使用，这样就更加的方便，于是就找到了swagger这个东东，还是很好用。下面介绍一下如何整合到springmvc中

1、在maven的pom文件中引入springfox的依赖

<!--springfox的核心jar包-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<!--springfox-ui的jar包(里面包含了swagger的界面静态文件)-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
<!--springfox依赖的jar包；如果你的项目中已经集成了无需重复-->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.9.0</version>
</dependency>

2、在源码目录下创建一个单独的package，然后创建SwaggerConfig.java文件

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/*重要！如果你的项目引入junit测试，此处需要使用@WebAppConfiguration，如果没有使用junit使用@Configuration(很多的博客都没有注明这个问题，为此我花了非常多的时间解决问题)*/
@WebAppConfiguration
@EnableSwagger2//重要！
@EnableWebMvc
@ComponentScan(basePackages = "com.XXXXX.control")//扫描control所在的package请修改为你control所在package
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX项目接口文档")
                .description("XXX项目接口测试")
                .version("1.0.0")
                .termsOfServiceUrl("")
                .license("")
                .licenseUrl("")
                .build();
    }
}

3、在springMVC的配置文件中配置swagger

<!--重要！将你的SwaggerConfig配置类注入-->
<bean class="com.XXXXX.config.SwaggerConfig"/>
<!--重要！配置swagger资源不被拦截-->
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />

4、修改web.xml文件中配置所有的请求都经DispatcherServlet处理

<servlet-mapping>
    <servlet-name>SpringMVC</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

注意： 这个地方必须配置，如果你配置的是*.XXX的形式会出现api-docs访问出错，这就会导致swagger-ui找不到api的有效路径。使swagger无法正常工作

5、controller的配置，配置测试swagger是否正常工作

/**
 * @author 欧阳思海
 * @date 2018/6/26 15:58
 */
@Api(value = "/coupon",tags = "优惠券接口")
@RestController
public class CouponController extends BaseController {

    //log4j日志
    private static final Logger logger = LoggerFactory.getLogger(CouponController.class);

    @Autowired
    private CouponService couponService;

    @RequestMapping(value = "/coupon/", method = RequestMethod.GET)
    @ApiResponses({
            @ApiResponse(code = 404, message = "服务器未找到资源"),
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 500, message = "服务器错误"),
            @ApiResponse(code = 401, message = "没有访问权限"),
            @ApiResponse(code = 403, message = "服务器拒绝访问"),
    })
    @ApiOperation(value="查询所有优惠券",httpMethod="GET",notes="查询所有优惠券",response=Coupon.class)
    public ResponseEntity<CouponResult> selectCouponList(){
        List<Coupon> coupons = null;
        CouponResult couponResult = new CouponResult();
        try {
            coupons = couponService.getCouponList();
            couponResult.setList(coupons);
            if (coupons == null || coupons.size() == 0){
                return sendCouponResultResponseEntity(HttpStatusEnum.getIndexByName("NOT_FOUND"), HttpStatusEnum.getKeyByName("NOT_FOUND"), couponResult);
            }
        } catch (Exception e){
            e.printStackTrace();
            return sendCouponResultResponseEntity(HttpStatusEnum.getIndexByName("INTERNAL_SERVER_ERROR"), HttpStatusEnum.getKeyByName("INTERNAL_SERVER_ERROR"), couponResult);
        }
        return sendCouponResultResponseEntity(HttpStatusEnum.getIndexByName("OK"), HttpStatusEnum.getKeyByName("OK"), couponResult);
    }

注解的详细信息移步：传送门

6、运行启动项目

我这里使用的是maven+tomcat的插件来启动项目的，不需要将其项目部署到本地tomcat。

访问的路径为：http://服务地址：端口/工程名/swagger-ui.html

运行效果如下：

这里写图片描述

如果你是使用本地的tomcat部署方式，方法如下：
这里写图片描述