在 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 文件并在 generates-sources 阶段替换 ${project.version} 占位符。因为openapi-generator-maven-plugin是同阶段执行的，定义在后面，所以会在资源过滤之后执行，结果会在target文件夹中的api spec上进行操作共 ${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@ 替换占位符应该可以解决这个问题。

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

Use artifact version number in OpenAPI spec definition

maven

swagger

swagger-ui

openapi

openapi-generator