个人认为swagger主要作用在于前后端分离项目服务端接口信息界面化，有助于接口的联调，当然也可以用于服务端接口测试（在header中加参数等等需要在Java端配置，比较麻烦，还不如直接使用postman），功能还是相当强大的。
1.首先引入swagger依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2.配置启动类的编写
swaggerConfig
具体代码如下
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
这是相当简洁的配置了，自动扫面所有的接口信息，@Configuration注解表明他是一个配置类，@EnableSwagger2开启swagger2。
3.解释接口信息的一些注解
- @Api：修饰整个类，描述Controller的作用
- @ApiOperation：描述一个类的一个方法，或者说一个接口
- @ApiParam：单个参数描述
- @ApiModel：用对象来接收参数
- @ApiProperty：用对象接收参数时，描述对象的一个字段
- @ApiResponse：HTTP响应其中1个描述
- @ApiResponses：HTTP响应整体描述
- @ApiIgnore：使用该注解忽略这个API
- @ApiError ：发生错误返回的信息
- @ApiParamImplicitL：一个请求参数
- @ApiParamsImplicit 多个请求参数
注：这里引用文章SpringBoot非官方教程 | 第十一篇：springboot集成swagger2，构建优雅的Restful API所写。
3.拦截器下的swagger配置与使用
拦截器配置的拦截路径包含了swagger的路径，这样会导致swagger-ui页面没用接口信息显示，所以就需要在拦截器配置"忽略路径",配置如下。
@Component
class WebMvcConfigurer extends WebMvcConfigurerAdapter {
//增加拦截器
public void addInterceptors(InterceptorRegistry registry){
if(swaggerShow){
registry.addInterceptor(new MyInterceptor()) //指定拦截器类
.addPathPatterns("/**") //指定该类拦截的url
.excludePathPatterns("/swagger-resources/**"); //指定不拦截url(swagger)
}else {
registry.addInterceptor(new MyInterceptor()) //指定拦截器类
.addPathPatterns("/**"); //指定该类拦截的url
}
}
}
上述的swaggerShow字段为配置在yml配置文件中是否开启swagger（一般在生产环境就关闭swagger，开发环境打开用于调式与接口的对接工作）
@Value("${swagger.show}")
private boolean swaggerShow;
swagger:
show: true
