Gravitee OSS Gateway代理Swagger UI返回404的配置排查与解决

一、先排查Gravitee API路由配置是否正确 #

你的404问题大概率是路由规则没覆盖到Swagger UI的相关路径，或是路由匹配逻辑有误：

• 进入Gravitee管理后台，找到MYAPI的「路由」配置页，检查默认路由的设置：
  • 确认路由路径为/myapi/**，目标为https://my-app.k8s.acme.fr/$request.path——这条规则会自动把/myapi之后的路径追加到后端目标地址后，比如请求/myapi/spring/swagger-ui/index.html，会转发到https://my-app.k8s.acme.fr/spring/swagger-ui/index.html
  • 如果没有这条路由，手动添加通用路由：路径填/myapi/**，目标填https://my-app.k8s.acme.fr/$request.path；或者更精准地添加/myapi/spring/**对应https://my-app.k8s.acme.fr/spring/$request.path
• 若路由配置正确仍报404，查看Gravitee网关日志，确认请求是否到达后端，以及后端是否返回404——有可能是后端服务的IP白名单限制了网关访问，需在后端允许网关IP。

二、解决Swagger UI静态资源加载异常问题 #

就算路由通了，你可能还会遇到Swagger UI页面空白、按钮失效的情况，这是因为Swagger UI的静态资源引用是基于原服务的/spring路径，通过网关访问时路径变为/myapi/spring，导致相对路径引用错误。有两种解决方式：

方法1：在Gravitee中添加响应重写策略 #

通过Gravitee的策略修改Swagger UI返回的HTML内容，替换资源路径：

1. 进入MYAPI的「策略」配置页，添加「响应重写」策略
2. 配置规则：
   • 匹配条件：响应Content-Type为text/html，且请求路径包含/swagger-ui/
   • 重写内容：把HTML中的/spring/swagger-ui/替换为/myapi/spring/swagger-ui/，同时将Swagger JSON的引用路径（比如/spring/api/v3/api-docs）替换为/myapi/spring/api/v3/api-docs

方法2：修改后端Swagger配置（若有权限操作后端） #

在后端Spring Boot服务的配置文件（application.yml或application.properties）中，指定Swagger的基础路径：

springdoc:
  swagger-ui:
    base-url: /myapi/spring/swagger-ui
  api-docs:
    path: /myapi/spring/api/v3/api-docs

这样Swagger UI生成的所有资源引用会自动带上/myapi前缀，适配网关的路径规则。

三、验证配置 #

完成配置后重启MYAPI，访问http://apim.local:8082/myapi/spring/swagger-ui/index.html：

• 打开浏览器开发者工具，检查所有请求的状态码，确保无404
• 测试Swagger UI的接口调用功能，确认网关能正常转发API请求

内容的提问来源于stack exchange，提问作者Ghassen