笔者这两天由于接口测试需要,给自己的项目添加了一下swagger,中间也碰到了一些问题,在这里记录一下。
目录
一、使用swagger之前必须添加的依赖
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
二、创建一个swagger配置文件
package com.muyichen.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 这是种对象可以创建多个,然后在swagger-ui的下拉框里会出现多个模块
* @return
*/
@Bean
public Docket createRestApi(){
// 添加请求参数,这里把token作为请求头部参数传入后端
ParameterBuilder parameterBuilder = new ParameterBuilder();
List<Parameter> parameters = new ArrayList<>();
parameterBuilder.name("Authorization")
.description("令牌")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false).build();
parameters.add(parameterBuilder.build());
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 默认扫描全路径
//.apis(RequestHandlerSelectors.any())
// 扫描指定路径
.apis(RequestHandlerSelectors.basePackage("com.muyichen.demo"))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(parameters);
}
/**
* 公共配置信息,这些信息会显示在swagger-ui.html页面上
* @return
*/
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("D+ 视频上传 API")
.description("This is a restful api document of Spring Boot.")
.version("1.0")
.build();
}
}
一般来说完成上述两步就可以使用swagger了,具体的接口注解和参数注解,请参考官方文档,这里就不一一赘述了,下面主要介绍的是配置过程中,常见的一些问题(笔者遇到过的)。
三、使用过程中常见的一些问题
1、访问/swagger-ui.html时,控制台打印404(找不到页面)
原因:一般出这个问题都是由于重写了WebMvcConfigurationSupport类中的addResourceHandlers()方法,使得Spring找不到swagger模块的对应路径导致。
解决办法:在重写的addResourceHandlers()方法中添加上swagger模块静态资源的对应路径,如下图
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/static/**")
.addResourceLocations(ResourceUtils.CLASSPATH_URL_PREFIX + "/static/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations(ResourceUtils.CLASSPATH_URL_PREFIX + "/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations(ResourceUtils.CLASSPATH_URL_PREFIX + "/META-INF/resources/webjars/");
super.addResourceHandlers(registry);
}
引申一下那个静态资源文件配置路径
笔者之前在网上查询修复方案的时候,发现有许多的博文中静态资源路径都是这样写的
可是笔者这样配置后,发现我前端页面的静态资源文件(CSS,JS之类的)找不到了,之后笔者改了下配置,变成了这样:
然后页面静态资源文件就能找到了。当然具体情况具体分析,笔者的页面没有做前后端分离,html中的静态资源文件路径前都加了/static前缀,所以菜肴这样调整,如果没有这个前缀的话,之前的写法也行。
2、扫包路径最好配置一下
笔者没有配置骚包路径的时候,默认是全路径扫描,然后扫出来的接口中有一部分是某些jar包中自带的,会影响后期对整个业务逻辑的梳理。
3、如何分服务配置多模块接口
这点在代码的注释中有写到过,主要就是在swagger配置文件中创建一个新的Docket对象(记住加上@Bean注解,让其注入Spring容器中),这个对象中配置对应服务的扫包路径就好了。