如何让OpenAPI Generator Maven插件使用pom.xml版本生成Spring Boot API

要让Swagger UI显示的API版本和pom.xml的${project.version}一致，核心是让生成时使用的OpenAPI规范文件中的info.version与项目版本同步——因为Swagger UI展示的是规范文件里的版本，而artifactVersion仅控制生成的构建文件（如子模块pom.xml）的版本，不影响API文档的版本显示。

下面是两种可行的解决方案：

方法一：Maven资源过滤替换规范文件版本 #

这是最直接的方案，通过Maven资源过滤将openapi.yml中的版本占位符替换为项目版本，再让插件使用过滤后的文件生成API。

1. 修改openapi.yml的版本为占位符 #

将原有的固定版本替换为Maven变量：

info:
  version: ${project.version}
  title: 你的API名称
  description: 你的API描述
  # 其他info字段

2. 在pom.xml中配置资源过滤和插件 #

开启资源过滤处理openapi.yml，并让插件指向过滤后的文件：

<build>
    <!-- 配置资源过滤，替换openapi.yml中的${project.version} -->
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
            <includes>
                <include>openapi.yml</include>
            </includes>
        </resource>
    </resources>

    <!-- 配置OpenAPI Generator插件 -->
    <plugins>
        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>6.6.0</version> <!-- 替换为你使用的插件版本 -->
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <!-- 指向过滤后的规范文件，位于编译输出目录 -->
                        <inputSpec>${project.build.outputDirectory}/openapi.yml</inputSpec>
                        <generatorName>spring</generatorName>
                        <configOptions>
                            <basePackage>com.your.company.api</basePackage>
                            <artifactVersion>${project.version}</artifactVersion> <!-- 控制生成构件的版本 -->
                            <!-- 你的其他配置项，如interfaceOnly、useSpringBoot3等 -->
                        </configOptions>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

执行mvn clean compile后，过滤后的openapi.yml会被放入target/classes目录，插件基于这个文件生成的API，其Swagger UI就会显示pom.xml中的项目版本。

方法二：自定义模板替换API文档版本 #

如果不想修改源openapi.yml，可以自定义OpenAPI Generator的模板，将API文档中的版本直接替换为${project.version}或插件配置的artifactVersion。

步骤： #

1. 从OpenAPI Generator的官方仓库中复制Spring生成器的模板文件（如api.mustache、swagger.mustache，路径通常为modules/openapi-generator/src/main/resources/JavaSpring）到你的项目目录（如src/main/resources/openapi-templates）。
2. 找到模板中引用info.version的位置，替换为{{artifactVersion}}（插件配置的artifactVersion值）或直接写${project.version}。
3. 在插件配置中指定自定义模板目录：

<configuration>
    <inputSpec>src/main/resources/openapi.yml</inputSpec>
    <generatorName>spring</generatorName>
    <templateDirectory>src/main/resources/openapi-templates</templateDirectory>
    <configOptions>
        <artifactVersion>${project.version}</artifactVersion>
        <!-- 其他配置 -->
    </configOptions>
</configuration>

这种方法适合需要保持源openapi.yml版本不变，但生成的API文档版本与项目对齐的场景。

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