maven - 在 OpenAPI 规范定义中使用 Artifact 版本号

标签 maven swagger swagger-ui openapi openapi-generator

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

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

问题是我不想维护版本号两次。所以我想在我的 api 规范中引用我的 maven pom 的版本号,而不是复制它,因为它有过时的风险。

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

这是来 self 的 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}
...

最佳答案

感谢@bcoughlan 的评论,我能够让 maven-resources-plugin 按需要工作。

现在它从 src/main/resources 文件夹中过滤 *yml 文件,并在 generates-sources 阶段替换 ${project.version} 占位符。因为openapi-generator-maven-plugin是同阶段执行的,定义在后面,所以会在资源过滤后执行,会在目标文件夹中的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@ 替换占位符应该可以解决这个问题。

关于maven - 在 OpenAPI 规范定义中使用 Artifact 版本号,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/57821746/

相关文章:

spring - 在 Spring Boot 中更改 swagger ui 基本路径

swagger - 如何在 Swagger 中定义空数组

springfox 2.2.2 没有生成 api 文档

python - 为什么 @api.doc 装饰器 python flask restplus 不更新我所做的更改?

java - 在 Ant 中使用 Maven 获取 jar 依赖项

REST API 设计指南合规性测试

java - 如何修复 spring boot 中损坏的 favicon.ico (而子文件夹中的 jpg-s 则没有)?

c# - .Net Core 2.2/Kestrel/Swagger 禁用分块/编码

java - Spring应用程序上下文无法在maven资源文件夹下找到属性文件

maven - Grails 更新后无法解析类 grails.plugin.cache.Cacheable