SpringMVC整合Springfox-Swagger

1
2
关于Swagger的简介就不占篇幅了...
本文使用的Springfox-Swagger版本为2.8.0

要整合Springfox-Swagger,只需要在Maven导入两个包即可,没有Maven下载导入也行…

1
2
3
4
5
6
7
8
9
10
<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的基本包,如果需要接口自动完成对象和JSON串的转换的话,需要再导入Jackson支持

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.6.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.6.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.6.5</version>
</dependency>

导入包以后,创建一个简单的Swagger配置类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
package net.sealin.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

// 仅在没有Spring-boot的项目中需要开启此配置
@EnableWebMvc
// 启用Swagger2
@EnableSwagger2
// 让Spring来加载该类配置
@Configuration
/**
* 也可在Spring配置文件中配置
* <context:component-scan base-package="net.sealin.controller"/>
*/
@ComponentScan(basePackages = "net.sealin.controller")
/**
* @author Sealin
* Created by Sealin on 2018-03-28.
*/
public class SwaggerConfig {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select()
//controller匹配规则
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}

private ApiInfo buildApiInf() {
return new ApiInfoBuilder()
.title("开放接口API")
.termsOfServiceUrl("http://localhost:8099/v2/api-docs")
.description("项目名称等描述性词语")
.contact(new Contact("Sealin", "http://www.sealin.net/", "admin@sealin.net"))
.version("1.0")
.build();

}
}

要让此配置类生效,需要Spring上下文配置中存在如下选项:

1
2
3
4
5
6
<!-- 让Swagger可以访问Controller -->
<mvc:annotation-driven />
<!-- 开启注解管理 -->
<context:annotation-config />
<!-- 将我们建立的配置类加入Spring容器 -->
<bean class="net.sealin.config.SwaggerConfig" />

1
2
3
4
5
6
7
8
<!-- 官方说明 -->
<!-- Required so springfox can access spring's RequestMappingHandlerMapping -->
<mvc:annotation-driven/>

<!-- Required to enable Spring post processing on @Configuration classes. -->
<context:annotation-config/>

<bean class="com.yourapp.configuration.MySwaggerConfig"/>

此外,因为我们用Spring实现的Servlet取代了默认的,在处理Swagger-UI的静态资源时,Spring-Servlet并不会帮我们映射这些资源文件,会导致不能访问swagger-ui.html的情况,两种方式可以解决这个问题,任选一种即可:
一.将没有@Controller解析的请求交给默认Servlet处理

1
<mvc:default-servlet-handler />

二.给Spring-servlet指定我们需要映射的资源文件路径

1
2
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

至此,Spring和Swagger的整合过程就告一段落了,运行试试:

1
2
3
4
API文档视图及操作界面:
http://127.0.0.1:8080/swagger/swagger-ui.html
所有API的汇总信息(JSON)
http://127.0.0.1:8080/swagger/v2/api-docs

遇到其他问题可以留言噢,祝君好运~