springMVC整合springfox 3.0实现swagger2在线接口文档

springMVC整合springfox 3.0实现swagger2在线接口文档

在这个springboot盛行的年代，想找点想要的资源是真的好难呀。springfox3.0跟之前的版本有很多的不同在跟springMVC整合时跟之前的版本多少有些不同，所以我在整个过程中碰到了很多意想不到的问题，这里做一下记录。也欢迎各位大佬指正。不多言，入正题。

整合步骤概括：

1. 导包（这个废了我很长的时间，后面遇到的很多问题都是因为包的问题）
2. SwaggerConfig.java文件
3. mvc配置文件

整合步骤详解：

1、导包：

网上很多资源都说只要到springfox-swagger2和springfox-swagger-ui两个包就可以，但我在使用的时候发现如果只导这两个包运行项目的时候会报ClassnotFoundException或者NoSuchMethodException的异常，我一点点的加，最后实际导入的包如下：

<spring.version>5.1.5.RELEASE</spring.version>
<spring.plugin.version>2.0.0.RELEASE</spring.plugin.version>
<swagger.version>3.0.0</swagger.version>
 <!-- swagger2 jar包 开始 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>com.google.guava</groupId>
                    <artifactId>guava</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-common</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-web</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-core</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spi</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!-- swagger2 jar包 结束 -->
        <!--spring插件包,整合swagger时导入-->
        <dependency>
            <groupId>org.springframework.plugin</groupId>
            <artifactId>spring-plugin-core</artifactId>
            <version>${spring.plugin.version}</version>
        </dependency>

具体原因我没有深究，但是我试过，缺任何一个包都会报错，特别时最后一个。

2、SwaggerConfig.java文件

先不多说，直接上代码

/**
 * @program: Steven
 * @description 注解信息：@EnableSwagger2 使swagger2生效 @ComponentScan(basePackages =
 *     {"com.steven.demo.controller"}) 需要扫描的controller包路径 @Configurable 配置注解，自动在本类上下文加载一些环境变量信息
 * @author: lenovo
 * @create: 2020/12/17 19:47
 */

@ComponentScan(basePackages = {"com.steven.demo.controller"})
@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {
  @Bean
  public Docket fileDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(buildApiInfo())
        .select()
        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        .paths(PathSelectors.ant("/StevenPro/fileInfo/**"))
        .build()
        .groupName("文件管理部分")
        .pathMapping("/");
  }

  @Bean
  public Docket shiroDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(buildApiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.steven.demo.controller.fileopr"))
        .paths(PathSelectors.any())
        .build()
        .groupName("操作管理部分")
        .pathMapping("/");
  }

  @Bean
  public Docket allDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .produces(Sets.newHashSet("application/json"))
        .consumes(Sets.newHashSet("application/json"))
        .protocols(Sets.newHashSet("http"))
        .forCodeGeneration(true)
        .select()
        .paths(regex(".*"))
        .build()
        .apiInfo(buildApiInfo())
        .groupName("全部接口展示");
  }

  private ApiInfo buildApiInfo() {
    return new ApiInfoBuilder()
        .title("StevenPro项目接口文档")
        .termsOfServiceUrl("https://blog.csdn.net/shengzhijian5?spm=1000.2115.3001.5343")
        .description("项目接口测试")
        .version("1.0.0")
        .contact(
            new Contact(
                "Steven",
                "https://blog.csdn.net/shengzhijian5?spm=1000.2115.3001.5343",
                "shengzhijian123@163.com"))
        .build();
  }
}

这里我写了三个@Bean我是做了一个分组，也是想模拟实际开发。实际做分组时我觉得可以通过文件所在文件夹.apis(RequestHandlerSelectors.basePackage("com.steven.demo.controller.fileopr"))设置分组，也可以通过实际接口路径.paths(PathSelectors.ant("/StevenPro/fileInfo/**"))设置分组。这个根据实际情况设置就好。
这个地方的注解@Configuration有的文章说在项目集成Junit的时候要换成@WebAppConfiguration，我的项目是使用了Junit的但是这两个注解都是可以的。

3、配置springmvc配置文件

这里只贴出跟swagger配置有关的部分：

<!--swagger2配置时，向容器自动注入配置-->
    <context:annotation-config/>
    <!--swagger2 静态资源映射-->
    <mvc:resources mapping="/swagger-ui/**" location="classpath:/META-INF/resources/webjars/springfox-swagger-ui/"/>
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
    <!-- 加载SwaggerConfig -->
    <bean id="swaggerConfig" class="com.steven.demo.utils.swagger.SwaggerConfig"/>

因为springfox-swagger-ui 3.0跟之前的包有很大的不同，所以在做静态资源映射时要做一些改变!

所以在最后项目启动后swagger的访问路径不在时swagger-ui.html,而是/swagger-ui/index.html.

我觉得实际上最大的困难就是导包。springboot的盛行是有原因的，在springboot中只要导一个包就行，在这里却要这么多。我在整合的过程中碰到很多问题，参考了很多优秀的文章，主要是这一篇感觉很有深度：

浅谈springfox-swagger原理解析与使用过程中遇到的坑：http://www.cppcns.com/ruanjian/java/221020.html