如何解决openapi-generator-maven-plugin使用已废弃类的问题？

你在整合Spring Boot和OpenAPI生成器时主要踩了两个核心坑：SpringDoc与SpringFox依赖冲突，以及生成代码依赖已废弃的SpringFox类却找不到替代类的正确依赖。下面一步步帮你解决：

1. 问题根源梳理 #

你同时引入了springdoc-openapi-*和springfox-*依赖，这两个都是OpenAPI/Swagger的实现框架，完全不能混装——它们的API、配置逻辑互斥，会导致大量类冲突或找不到的问题。

另外，默认的openapi-generator-maven-plugin的spring生成器，默认输出SpringFox风格的配置代码（也就是你看到的OpenAPIDocumentationConfig，用到了SpringFox的RelativePathProvider），而你后来注释掉了SpringFox依赖，自然会出现类缺失的错误。

2. 方案一：推荐使用SpringDoc（适配现代Spring Boot） #

SpringDoc是专为Spring Boot设计的OpenAPI 3实现，维护更活跃，也无需处理SpringFox的废弃类问题。我们需要调整插件配置，让它生成SpringDoc兼容的代码，同时清理所有SpringFox依赖：

调整后的完整POM配置 #

<properties>
    <java.version>11</java.version>
    <springdoc.version>1.5.5</springdoc.version>
    <openapi-generator.version>5.0.1</openapi-generator.version>
</properties>

<dependencies>
    <!-- SpringBoot核心依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>

    <!-- SpringDoc OpenAPI依赖 -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>${springdoc.version}</version>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-data-rest</artifactId>
        <version>${springdoc.version}</version>
    </dependency>

    <!-- OpenAPI生成器所需的nullable支持 -->
    <dependency>
        <groupId>org.openapitools</groupId>
        <artifactId>jackson-databind-nullable</artifactId>
        <version>0.2.1</version>
    </dependency>

    <!-- Lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.16</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

<build>
    <finalName>app</finalName>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-configuration-processor</artifactId>
                    </exclude>
                </excludes>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>${openapi-generator.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <generatorName>spring</generatorName>
                        <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
                        <configOptions>
                            <!-- 指定生成SpringDoc兼容的代码 -->
                            <library>spring-boot</library>
                            <springdoc>true</springdoc>
                            <sourceFolder>src/java/main</sourceFolder>
                            <output>${project.build.directory}/generated-sources</output>
                        </configOptions>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

关键调整点：

• 完全移除所有springfox-*依赖，只保留SpringDoc
• 在插件configOptions中添加<springdoc>true</springdoc>和<library>spring-boot</library>，让生成器输出SpringDoc风格代码，不再生成依赖SpringFox的OpenAPIDocumentationConfig

3. 方案二：如果坚持使用SpringFox（不推荐） #

若你一定要用SpringFox，需解决DefaultPathProvider的依赖问题：这个类属于springfox-spring-web模块，需确保引入该依赖，同时清理SpringDoc依赖：

必要依赖补充 #

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-spring-web</artifactId>
    <version>${springfox.version}</version>
</dependency>

注意：SpringFox 3.x已停止维护，后续可能会出现更多废弃类或兼容性问题，不推荐长期使用。

4. 修正你的OpenAPI YAML语法错误 #

你提供的openapi.yaml存在两处语法问题，修正后如下：

openapi: 3.0.3
info:
  title: Title
  description: "REST API Dokumentation xxx"
  version: ${artifactId}
  termsOfService: http://swagger.io/terms/
  contact:
    name: API Support
    email: xxx.yyy@zzz.de
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: http://{domain}:{port}
    description: The local server
    variables:
      domain:
        default: localhost
        description: api domain
      port:
        enum:
          - '8081'
        default: '8081'
paths:
  /api/hello/{name}: # 补充path参数占位符
    get:
      summary: Says 'hello' to the user.
      description: A test endpoint.
      parameters:
        - in: path
          name: name
          required: true
          schema:
            type: string
          description: The person's name to address to.
      responses:
        '200':
          description: Ok
          content: # 修正content的缩进层级
            application/json:
              schema:
                type: string
        '500':
          description: Server error
        default:
          description: Unexpected error

内容的提问来源于stack exchange，提问作者du-it