一、Swagger2简单介绍
Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。
二、Spring Boot集成Swagger2步骤
1)引入Swagger2的Maven坐标
<!--swagger-->
<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>
2) 加入Swagger2的Java配置类
import org.springframework.context.annotation.Configuration;
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;/**
* @author zhangboqing
* @date 2018/8/6
*
* swagger2配置
*
* 访问地址:
* http://localhost:8080/swagger-ui.html
*/
@Configuration
@EnableSwagger2
public class Swagger2Config { @Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
//当前包路径
.apis(RequestHandlerSelectors.basePackage("com.zbq.springbootbase.controller"))
.paths(PathSelectors.any()).build(); } //构建api文档的详细信息函数
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("springboot-base-frame,使用Swagger2构建RESTful API")
//创建人
.contact(new Contact("张波清", "756623607@qq.com", ""))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build(); }}
3)在Controller方法上加上 @ApiOperation(value=”测试”, notes=”这是一个简单测试方法”),再不用加任何注解。
/**
* @author zhangboqing
* @date 2018/9/24
*/
@RestController
public class TestController { @ApiOperation(value="测试", notes="这是一个简单测试方法")
@PostMapping(value = "/test")
public String test(@RequestHeader String myHeader,String myName) {
System.out.println("----------->header测试"); System.out.println(myHeader);
System.out.println(myName);
return myHeader;
}}
4)若使用了Spring Boot 的拦截器,需要过滤Swagger,确保它不被拦截
加入如下标记为蓝色的过滤配置,就可以了
/**
* @author zhangboqing
* @date 2018/8/7
*
* 注册拦截器
*/
@Configuration
public class ApiSecurityConfig2 implements WebMvcConfigurer { @Bean
LoggingInterceptor loggingInterceptor() {
return new LoggingInterceptor();
} /**
* 拦截请求
*
* @param registry
*/
@Override
public void addInterceptors(InterceptorRegistry registry) {
//注册日志拦截器
registry.addInterceptor(loggingInterceptor())
//添加需要拦截的路径
.addPathPatterns("/**")
.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**"); } @Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
} /**
* 跨域配置
*
* @param registry
*/
@Override
public void addCorsMappings(CorsRegistry registry) {
// registry.addMapping("/**")
// // TODO 这里跨域最好配置域名
// .allowedOrigins("*")
// .maxAge(3600)
// .allowCredentials(true)
// .allowedMethods("GET", "POST", "OPTIONS");
}
}
三、效果展示
启动你的项目,访问Swagger2文档地址:http://localhost:8080/swagger-ui.html