Spring REST API与OpenApi上下文路径重复调用问题及解决咨询

问题原因 #

• OpenAPI定义文件my-api-v1.yaml的servers.url包含了/my-api/v1前缀，openapi-generator-maven-plugin的spring生成器默认会将该前缀作为控制器接口的路径前缀（比如生成的/users接口会变成/my-api/v1/users）。
• 同时Spring的application.yml中配置了server.servlet.context-path: /my-api/v1，这会给整个应用的所有接口再添加一层相同的前缀。
• 两者叠加后，实际有效接口路径变成了/my-api/v1/my-api/v1/users，而你预期的/my-api/v1/users因路径不匹配返回400错误，重复前缀的路径反而能正常访问。

修复方案 #

以下方案均可解决问题，同时保证Swagger UI的「Try it out」功能正常使用：

方案1：通过Generator配置剥离OpenAPI中的BasePath #

保留现有my-api-v1.yaml和application.yml的配置，仅修改Maven插件配置，让生成的控制器接口不带OpenAPI定义中的前缀：

• 在pom.xml的openapi-generator-maven-plugin配置中添加removeBasePathFromUrls参数：

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>你的插件版本号</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <generatorName>spring</generatorName>
        <inputSpec>${project.basedir}/src/main/resources/my-api-v1.yaml</inputSpec>
        <!-- 核心配置：移除OpenAPI定义中的basePath，避免路径重复 -->
        <removeBasePathFromUrls>true</removeBasePathFromUrls>
        <!-- 其他原有配置（如包名、模型生成规则等） -->
      </configuration>
    </execution>
  </executions>
</plugin>

• 重新生成代码后，控制器接口路径仅为OpenAPI中定义的相对路径（如/users），结合Spring的context-path，最终有效路径为/my-api/v1/users，与Swagger UI显示的路径一致。

方案2：修改OpenAPI的Servers配置，移除上下文路径 #

• 修改my-api-v1.yaml的servers配置，仅保留域名和端口：

servers:
  - url: http://localhost:9001

• 保留Spring的server.servlet.context-path: /my-api/v1配置，生成的控制器接口路径为OpenAPI中定义的相对路径（如/users），最终有效路径为/my-api/v1/users。
• 若要让Swagger UI自动带上上下文路径，可在OpenAPI中使用变量定义：

servers:
  - url: http://localhost:9001{basePath}
    variables:
      basePath:
        default: /my-api/v1

方案3：移除Spring的上下文路径配置 #

• 注释掉application.yml中的server.servlet.context-path: /my-api/v1。
• 保留my-api-v1.yaml的原有servers配置，生成的控制器接口会自动带上/my-api/v1前缀，直接访问http://localhost:9001/my-api/v1/users即可正常调用，Swagger UI的「Try it out」功能也能正常工作。

推荐方案 #

优先选择方案1，既能保留OpenAPI定义中完整的服务器路径（方便Swagger UI直接使用），又能通过插件配置灵活控制路径生成规则，后续调整上下文路径时无需修改OpenAPI文件，仅需调整Spring配置即可。

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