Spring Boot 自定义 Swagger2 请求 URL 路径的两种方法
前言
首先，把 Swagger2 的依赖引进来：
<!--swagger 版本-->
<swagger.version>2.7.0</swagger.version>
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
然后，建立 Swagger2 的配置文件：
@EnableSwagger2
@Configuration
@Profile({"qa", "rd", "beta"})
public class Swagger2Config extends WebMvcConfigurerAdapter {
@Value("${swagger.enable:false}")
private boolean enableSwagger;
@Bean
public Docket controllerApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(enableSwagger)
.select()
.apis(RequestHandlerSelectors.basePackage("com.hit.math.web"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文档")
.description("Swagger2-接口文档")
.version("v1.0.0")
.build();
}
}
默认情况下，Swagger2 的访问路径为：
http://localhost:端口/swagger-ui.html
如果我们想要修改上述的请求路径，则需要进行一些修改。
在这里，以 Spring Boot 项目为例，给出两种自定义 Swagger2 请求 URL 路径的方法。
方法一：修改应用根路径
对于第一种方法，非常简单，我们只需要在application.yml文件中，新增以下配置即可：
server:
port: 8215
tomcat:
basedir: /tmp/tomcat
servlet: # 添加统一服务前缀
context-path: /selfpath
如上述配置所示，其中/selfpath就是我们修改的应用根路径，也是我们自定义的请求路径。
新增上述配置之后，再想访问 Swagger2，地址就应该是：
http://localhost:端口/selfpath/swagger-ui.html
方法二：引入 Swagger2 前端代码
对于第二种方法，说实话，不太好，但在某些限制我们修改应用根路径的情况下，也能解决我们的问题。
具体的操作步骤，如下：
- GitHub: swagger-ui
Step 1：访问swagger-ui代码仓库，选择一个 2.0 以上、3.0 以下的版本，将其中的dist文件夹拷贝到我们自己项目中的resources/swagger目录下，如下图所示
Step 2：在resources下新建swagger.properties文件，其中的内容为
springfox.documentation.swagger.v2.path=/selfpath/swagger
Step 3：修改dist目录下面的index.html页面，文件内搜索以下内容
url = "http://petstore.swagger.io/v2/swagger.json";
将其替换为
url = "/selfpath/swagger";
替换后，该部分的代码大致为
......
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
// url = "http://petstore.swagger.io/v2/swagger.json";
url = "/selfpath/swagger";
}
hljs.configure({
highlightSizeThreshold: 5000
});
// Pre load translate...
if(window.SwaggerTranslator) {
window.SwaggerTranslator.translate();
}
......
Step 4：修改Swagger2Config配置文件
@EnableSwagger2
@Configuration
@Profile({"qa", "rd", "beta"})
@PropertySource("classpath:swagger.properties")
public class Swagger2Config extends WebMvcConfigurerAdapter {
@Value("${swagger.enable:false}")
private boolean enableSwagger;
@Bean
public Docket controllerApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(enableSwagger)
.select()
.apis(RequestHandlerSelectors.basePackage("com.hit.math.web"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文档")
.description("Swagger2-接口文档")
.version("v1.0.0")
.build();
}
}
与开篇处的配置文件相比，新增了@PropertySource("classpath:swagger.properties")注解，扫描指定的配置文件。
Step 5：添加资源的映射
@Configuration
public class InterceptorConfig extends WebMvcConfigurerAdapter {
/**
* Swagger 增加 url 映射
*
* @param registry 注册器
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/selfpath/swagger/**").addResourceLocations("classpath:/swagger/dist/");
}
}
按上述的步骤操作完之后，剩下的就是进行验证了。但与第一种方法不同，使用第二种方法配置完之后，Swagger2 的访问路径应该为：
http://localhost:端口/selfpath/swagger/index.html
其中，我们自定义的路径为/selfpath，在实际使用的时候，可以根据需要进行替换。
总结
对于本文所述的两种方法，博主都在实际的项目中使用过。最后，简单总结一下：
- 推荐第一种方法，修改应用根路径，简单易用，而且不影响我们后续升级 Swagger2 的版本；
- 不推荐第二种方法，引入 Swagger2 前端代码，对我们的项目侵入性太大，而且影响我们后续升级 Swagger2 的版本。
特别地，在swagger-ui的 3.0 版本之后，该项目调整了目录结构，已经没有dist目录了。
参考资料：