在 OpenAPI 规范定义中使用工件版本号

Question

我有一个 Maven 项目，其中的 API 定义使用 OpenaAPI v3 规范。

我使用 openapi-generator-maven-plugin 生成代码，一切正常。我还可以访问 swagger-ui 并查看和测试我的 API。

问题是我不想两次维护版本号。因此，我想在 api 规范中引用我的 maven pom 中的版本号，而不是冒着过时风险进行复制。

我尝试过maven资源过滤，这似乎有效。由于当我将版本字段放入规范中时，目标文件夹中的 yaml 文件会被很好地替换${project.version}，但是当我打开 swagger-ui 时，它会按字面意思打印“${project.version}”而不是实际版本。

这是我的 pom 中的插件配置：

<build>
      <resources>
        <resource>
          <directory>src/main/resources</directory>
          <filtering>true</filtering>
        </resource>
      </resources>
      <plugins>
        <plugin>
          <groupId>org.openapitools</groupId>
          <artifactId>openapi-generator-maven-plugin</artifactId>
          <version>${openapi-generator-maven-plugin.version}</version>
          <executions>
            <execution>
              <goals>
                <goal>generate</goal>
              </goals>
              <configuration>
                <inputSpec>${project.build.resources[0].directory}/spec.yml</inputSpec>
                <ignoreFileOverride>${project.build.resources[0].directory}/.openapi-codegen-ignore</ignoreFileOverride>
                <language>spring</language>
                <library>spring-boot</library>
                <configOptions>
                  <!-- Use the newer java.time package instead of outdated java.util-->
                  <dateLibrary>java8</dateLibrary>
                </configOptions>
                <apiPackage>${default.package}.api</apiPackage>
                <modelPackage>${default.package}.model</modelPackage>
                <invokerPackage>${default.package}.invoker</invokerPackage>
                <generateApiTests>false</generateApiTests>
              </configuration>
            </execution>
          </executions>
       </plugin>
       ...
    </plugins>
</build>

这是我的spec.yml：

openapi: 3.0.0
info:
  version: ${project.version}
...

Answer 1

感谢 @bcoughlan 的评论，我能够让 maven-resources-plugin 按预期工作。

现在，它会从 src/main/resources 文件夹中过滤 *yml 文件，并在此阶段替换 ${project.version} 占位符generates-sources。因为openapi-generator-maven-plugin是同阶段执行的，并且是稍后定义的，所以它会在资源过滤之后执行，并且会对目标文件夹中的api规范进行操作，结果是：${project.build.outputDirectory}/spec.yml

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-resources-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
          <resources>
            <resource>
              <directory>src/main/resources</directory>
              <filtering>true</filtering>
            </resource>
          </resources>
        </configuration>
        <executions>
          <execution>
            <phase>generate-sources</phase>
            <goals>
              <goal>resources</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <!-- Codegen plugin for api. Depends on maven-resources-plugin to have executed in the generate-sources phase! -->
      <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>${openapi-generator-maven-plugin.version}</version>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.build.outputDirectory}/spec.yml</inputSpec>
                <ignoreFileOverride>${project.basedir}/.openapi-codegen-ignore</ignoreFileOverride>
              <language>spring</language>
              <library>spring-boot</library>
              <configOptions>
                <!-- Use the newer java.time package instead of outdated java.util-->
                <dateLibrary>java8</dateLibrary>
              </configOptions>
              <apiPackage>${default.package}.api</apiPackage>
              <modelPackage>${default.package}.model</modelPackage>
              <invokerPackage>${default.package}.invoker</invokerPackage>
              <generateApiTests>false</generateApiTests>
            </configuration>
          </execution>
        </executions>
      </plugin>

注意：openapi-generator-maven-plugin 与 swagger-codegen-maven-plugin 几乎相同。有关差异的更多信息可以在这里找到：https://openapi-generator.tech/docs/fork-qna

注意2：当使用spring-boot父pom时，您继承了resource.delimeter=@属性，并且${project.version}符号不再起作用。因此，用 替换占位符@project.version@应该可以解决这个问题。