SSM三大框架整合Springfox(Swagger2)步骤以及遇到的一些问题

需求是在已有的Spring+SpringMVC+Mybatis的项目中整合Springfox(Swagger2)。

在网上查看了非常多的博客，均没有解决问题。经过一天多的摸索，总算是成功的完成了整合。现在将具体的步骤记录下来，希望能给有需求的朋友提供参考。

注意：此篇文章仅讲解整合完成SSM三大框架以后整合Springfox(Swagger2)

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

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.7.0version>
dependency>

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.7.0version>
dependency>

<dependency>
    <groupId>com.fasterxml.jackson.coregroupId>
    <artifactId>jackson-databindartifactId>
    <version>2.9.0version>
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

<mvc:default-servlet-handler />

<context:annotation-config />

<context:component-scan base-package="com.XXXXX"/>

<bean class="com.XXXXX.config.SwaggerConfig"/>

<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>SpringMVCservlet-name>
    <url-pattern>/url-pattern>
servlet-mapping>

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

@Controller
@RequestMapping("/user")
@Api(value = "/user", tags = "User接口")
public class UserController {

    private static Logger logger = Logger.getLogger(UserController.class);
    @Autowired
    private UserService userService;

    @RequestMapping(value = "/getUser/{id}",method = RequestMethod.GET)
    @ResponseBody
    @ApiOperation(value = "根据id获取用户信息", notes = "根据id获取用户信息", httpMethod = "GET", response = User.class)
    public ResponseEntity getUser(@PathVariable int id){
        User user = userService.getUserById(id);
        logger.info("controller:"+user);
        return ResponseEntity.ok(user);
    }
}

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

运行：我这里使用Tomcat8.5.16和jetty9.4.6都能够正常的工作

---

2017-12-11补充
访问地址：[项目访问地址]/swagger-ui.html
例如本地Tomcat运行swagger-demo,那么访问地址为：http://localhost:8080/swagger-demo/swagger-ui.html