SpringBoot - SWAGGER中配置.pathMapping(“XXXX“)引发的404错误

写在前面

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");
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

问题分析

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。