Kubernetes路径转发下Swagger API请求地址错误问题

这问题我之前帮好几个开发者排查过，核心原因是Swagger UI没意识到它是在/mt这个子路径下运行的，所以生成API请求时直接用了域名根路径，导致请求变成www.example.com:443/api/...，而不是预期的www.example.com/mt/api/...。下面给你几个靠谱的解决思路，从Ingress配置到应用本身调整都覆盖到了：

方案1：调整Ingress配置（适配Nginx Ingress Controller） #

如果你的集群用的是Nginx Ingress，我们可以通过路径重写和请求头传递来让应用感知到子路径前缀。这里是一个示例Ingress YAML：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mt-swagger-ingress
  annotations:
    # 重写路径：把/mt之后的部分转发到容器的对应路径
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    # 给后端应用传递前缀信息，让Swagger能读取到
    nginx.ingress.kubernetes.io/proxy-set-header: "X-Forwarded-Prefix /mt"
spec:
  tls:
  - hosts:
    - www.example.com
    secretName: example-tls # 替换成你的HTTPS证书Secret
  rules:
  - host: www.example.com
    http:
      paths:
      - path: /mt(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: mt-app-service # 替换成你的Service名称
            port:
              number: 8080

这个配置会把www.example.com/mt/api/xxx转发到容器的/api/xxx，同时通过X-Forwarded-Prefix告诉应用它的访问前缀是/mt，大部分Swagger框架都能读取这个头来自动修正API路径。

方案2：修改Swagger应用的配置（从源头解决） #

直接在应用代码里指定Swagger的基础路径，这样生成的API文档会自带/mt前缀，前端UI自然会用正确的路径发起请求。这里分两种常见框架举例：

如果你用的是Spring Boot + SpringFox（Swagger 2） #

在Swagger配置类里添加pathMapping：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.app.package"))
                .paths(PathSelectors.any())
                .build()
                .pathMapping("/mt") // 指定API的基础前缀
                .host("www.example.com"); // 可选：指定完整的域名
    }
}

如果你用的是Spring Boot + SpringDoc（OpenAPI 3） #

通过@OpenAPIDefinition指定Server路径：

@Configuration
@OpenAPIDefinition(
        servers = {
                @Server(url = "/mt", description = "API基础访问路径")
        }
)
public class OpenApiConfig {
    // 其他配置...
}

方案3：纯前端Swagger UI的调整 #

如果你的Swagger UI是独立部署的前端应用，在初始化Swagger UI时直接指定basePath：

const ui = SwaggerUIBundle({
  url: "/mt/v3/api-docs", // 指向带前缀的API文档地址
  basePath: "/mt", // 设置API请求的基础前缀
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  layout: "StandaloneLayout"
});

排查验证步骤 #

• 先测试Ingress路径是否正常：用curl https://www.example.com/mt/api/your-test-endpoint，确认能拿到正确的响应，排除Ingress转发问题。
• 访问https://www.example.com/mt/v2/api-docs（或v3），查看返回的JSON里的basePath或servers字段，确认是否包含/mt前缀。
• 刷新Swagger UI页面，再发起API请求，检查请求地址是否已经变成www.example.com/mt/api/...。

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