Spring MVC非Boot项目中如何修正Swagger生成的Controller API请求URL？

问题描述 #

在非Spring Boot的Java Spring MVC项目（手动部署到Tomcat 9.0）中集成Swagger 3，当前Swagger UI的访问URL为：

http://localhost:8080/kes/v1.0/swagger-ui/index.html

但调用任意Controller接口时，Swagger自动生成的请求URL出现路径顺序错误：

实际生成: http://localhost:8080/v1.0/kes/[接口路径]
期望路径: http://localhost:8080/kes/v1.0/[接口路径]

该问题直接导致接口请求404，尝试修改web.xml中的URL模式后未解决问题。

当前配置信息 #

依赖配置（pom.xml） #

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
    <!--scope>compile</scope-->
</dependency>

Swagger配置类 #

package com.pen.lis.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
        .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
    }

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.eds.kes.controller")).build();
    }
}

解决方案 #

1. 修正Swagger的根路径映射 #

在Docket配置中添加pathMapping，明确指定项目的完整根路径（上下文路径+接口前缀），让Swagger生成URL时遵循正确的路径顺序：

@Bean
public Docket productApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.eds.kes.controller"))
            .build()
            .pathMapping("/kes/v1.0"); // 指定完整根路径
}

2. 检查并修正web.xml的DispatcherServlet配置 #

确保DispatcherServlet的url-pattern与接口前缀匹配，示例配置如下：

<servlet>
    <servlet-name>springmvc</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath:spring-mvc.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>springmvc</servlet-name>
    <url-pattern>/v1.0/*</url-pattern>
</servlet-mapping>

注：此时项目上下文路径为kes，完整接口根路径即为/kes/v1.0/，与pathMapping配置保持一致。

3. 适配Swagger UI资源路径 #

修改addResourceHandlers方法，确保Swagger UI资源能正确映射到上下文路径+前缀：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/kes/v1.0/swagger-ui/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
}

4. 验证效果 #

重启Tomcat后访问Swagger UI，查看接口请求URL是否修正为http://localhost:8080/kes/v1.0/[接口路径]，测试接口是否能正常调用。

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