根据需求我需要在SSM项目中整合Swagger,我这里所用的swagger为2.0以上版本。
1.首先要引入依赖,需要注意的是如果swagger版本与spring版本不匹配,访问swagger可能会报错500,这个时候需要在pom文件中降低swagger版本,或升高spring版本。示例代码:
<!--springfox的核心jar包-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<!--springfox-ui的jar包(里面包含了swagger的界面静态文件)-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.9.0</version>
<!-- <version>2.9.5</version> -->
</dependency>
<!-- Google的Java常用类库 -->
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>26.0-jre</version>
</dependency>
<!-- web端静态资源的jar包 -->
<dependency>
<groupId>org.webjars</groupId>
<artifactId>bootstrap</artifactId>
<version>3.3.5</version>
</dependency>
2.编写swagger工具类,示例代码:
package com.gx.util;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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
*/
@Configuration
@EnableSwagger2 // 重要!
//@EnableWebMvc
@ComponentScan(basePackages = {
"com.gx.web" }) // 扫描control所在的package请修改为你control所在package
// 如果要访问的话直接访问 http://localhost:8080/项目名称/swagger-ui.html 就可以访问到文档了
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()//选择哪些路径和API会生成document
//扫描指定包中的swagger注解
//.apis(RequestHandlerSelectors.basePackage("com.gx.web"))
//扫描所有有注解的api,用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//扫描所有的api(没有添加注解也可以扫描出来),用这种方式更直接
//.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
/**
* 这是匹配api的信息
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 大标题
.title("API接口文档")
// 描述
.description("API接口测试")
// 版本号
.version("1.0.0")
.termsOfServiceUrl("").license("").licenseUrl("").build();
}
}
3.在springMVC的配置文件中配置swagger,示例代码:
<!--将静态资源交由默认的servlet处理-->
<mvc:default-servlet-handler />
<!--向容器自动注入配置-->
<context:annotation-config />
<!--自动扫描,使springMVC认为包下用了@controller注解的类是控制器-->
<context:component-scan base-package="com.gx.web"/>
<!--重要!将你的SwaggerConfig配置类注入-->
<bean class="com.gx.util.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>
5.在controller中添加swagger注解@Api和@ApiOperation,@Api()用于类——表示标识这个类是swagger的资源,@ApiOperation()用于方法——表示一个http请求的操作,示例代码:
@Controller
@RequestMapping("/user")
@Api(value = "用户接口", description = "用户相关api")
public class UserController {
@Autowired
private IUserService userService;
// 登录页面
@RequestMapping("/loginsPage")
@ApiOperation(value = "登录", notes = "后台登录",httpMethod = "GET", response = ModelAndView.class)
public ModelAndView loginsPage() {
ModelAndView mv = new ModelAndView("/login");
return mv;
}
}
6.运行项目(我这里使用本地Tomcat运行项目),在浏览器中访问,效果截图:
访问地址:http://localhost:8080/项目名称/swagger-ui.html