写在前面
SpringBoot - SWAGGER2的集成与使用(一)
SpringBoot - SWAGGER2公共模块的抽象集成与使用(二)
SpringBoot - SWAGGER3公共模块的抽象集成与使用(三)
SpringBoot - 集成SWAGGER的常见问题
问题描述
A. 前端UI将SWAGGER-UI集成到系统的菜单中了,SWAGGER-UI是用iframe形式打开的;
B. 直接在前端UI的菜单中访问SWAGGER-UI正常,接口访问正常;
C. 如果直接使用:http://后端服务地址:后端端口/swagger-ui/index.html访问SWAGGER-UI,页面显示正常,但是测试接口的时候报404错误;
D. SWAGGER的配置如下:
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
// 是否启用Swagger
.enable(enabled)
// 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息)
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api, 用这种方式更灵活(本系统默认方式)
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描指定包中的swagger注解
.apis(RequestHandlerSelectors.basePackage("cn.hadoopx.web.controller.system"))
// 扫描所有
//.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
/* 设置安全模式,swagger可以设置访问token */
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.pathMapping("/dev-api");
}
问题分析
A. 为什么直接在前端UI的菜单中访问SWAGGER-UI正常,接口访问正常?
在前后端分离架构上,SWAGGER-UI使用iframe方式嵌套,生成的服务地址也是前端暴露的地址端口,然后请求过来时将请求代理到后端的目标地址上,同时前端会去掉’.pathMapping(“/dev-api”)'设置的请求前缀,所以访问是正常的。
B. 为什么直接使用:http://后端服务地址:后端端口/swagger-ui/index.html访问SWAGGER-UI,页面显示正常,但是测试接口的时候报404错误?
.pathMapping(“/dev-api”),只是一个附加的虚拟的路径,并没有实际映射作用到对应的@RequestMapping的路径上,实际的访问路径依然是去掉请求前缀"/dev-api"的,但是它会作用到生成SWAGGER-DOC里的API路径上,会在API路径的前面拼接上前缀,所以直接访问会报错。
C. 如何解决?
第一种方式:针对这个情况可以写个全局过滤器,将请求路径的前缀去掉;
第二种方式:测试的时候,不使用SWAGGER,直接使用POST-MAN测试,使用服务接口真实的调用地址+端口(不带/dev-api前缀);
第三种方式:直接通过前端的UI菜单来访问SWAGGER-UI。