OpenAPI Generator未将上下文路径加入请求URL的问题解决

规范层面：写法合法，问题出在工具默认行为 #

OAS 3.0 中servers.url定义的是API的基础服务地址，paths里的路径是相对这个地址的片段，把/details/v2移到servers.url的写法完全符合规范，不存在规范层面的问题。问题根源在openapi-generator v4.3.1的默认处理逻辑上。

openapi-generator 默认行为说明 #

这个版本的代码生成器在生成Spring控制器时，只会将paths中定义的路径片段（也就是/address）写入@RequestMapping注解，不会自动把servers.url里的路径前缀合并进去。这是工具的默认配置逻辑，和OAS规范无关。

两种可行解决办法 #

方法1：添加生成器前缀配置 #

通过apiPrefix参数指定路径前缀，让生成器自动将前缀与paths中的路径拼接。

• 命令行示例：

  openapi-generator generate -i your-api-spec.yaml -g spring -o target/generated-sources --api-prefix=/details/v2
  

• Maven插件配置示例：

  <plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>4.3.1</version>
    <executions>
      <execution>
        <goals>
          <goal>generate</goal>
        </goals>
        <configuration>
          <inputSpec>${project.basedir}/src/main/resources/api-spec.yaml</inputSpec>
          <generatorName>spring</generatorName>
          <apiPrefix>/details/v2</apiPrefix>
          <!-- 其他生成配置 -->
        </configuration>
      </execution>
    </executions>
  </plugin>
  

方法2：回退原规范写法 #

把/details/v2移回paths中，保持servers.url为https://my.api.com/employee，生成器默认就会将完整的/details/v2/address写入@RequestMapping注解，无需额外配置。

内容的提问来源于stack exchange，提问作者Runtime Terror - BS