Open API 代码生成器 Maven 插件使用旧的 Swagger 2 注释而不是 Swagger 3 注释答案

【问题标题】：Open API code generator Maven plugin uses old Swagger 2 annotations instead of Swagger 3 annotationsOpen API 代码生成器 Maven 插件使用旧的 Swagger 2 注释而不是 Swagger 3 注释
【发布时间】：2020-07-15 13:06:42
【问题描述】：

我正在使用 Open API 代码生成器 Maven 插件从文件生成 Open API 3.0。我在我的 pom.xml 中使用了这个插件：

<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.3.0</version>

插件生成 API 时没有任何问题，但它不使用 Swagger v3 注释，而是使用旧的 Swagger 注释。例如参数使用@ApiParam注解，而不是@Parameter注解应该使用io.swagger.v3.oas.annotations包：

default ResponseEntity<Fault> getFault(@ApiParam(value = "",required=true) @PathVariable("jobId") String jobId) {

因此，最新的 Swagger UI 无法正确显示文档。当我使用 swagger.v3 注释创建端点时，Swagger UI 工作正常。

根据官网https://openapi-generator.tech/docs/plugins/，我应该包含这个依赖：

<dependency>
    <groupId>io.swagger.parser.v3</groupId>
    <artifactId>swagger-parser</artifactId>
</dependency>

但即使有这种依赖关系，插件仍然会生成带有旧注释的源代码。

如何强制 Open API 代码生成器使用 Swagger v3 注释？

【问题讨论】：

你找到解决办法了吗？

标签： spring maven swagger openapi openapi-generator

【解决方案1】：

目前不支持 V3 注释。

您需要覆盖 mustache 模板。

查看这些 PR：
https://github.com/OpenAPITools/openapi-generator/pull/4779
https://github.com/OpenAPITools/openapi-generator/pull/6306

您可以使用上述 PR 中的升级模板或在合并时等待。

【讨论】：

你知道有没有进展吗？开了好久了……
这方面有什么更新吗？
最新版本（5.3.1 版）合并了这个github.com/OpenAPITools/openapi-generator/pull/9775 Spring 代码生成器现在支持 v3 注释——我在实际项目中使用它——但我不是 100%满意（我还有一些模板修改）

【解决方案2】：

现在该插件的 5.3.1 版本已发布，我使用来自 https://github.com/OpenAPITools/openapi-generator/pull/9775 和 https://github.com/OpenAPITools/openapi-generator/issues/6108 的信息使其适合我。

我在pom.xml中添加了三个configOptions：

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>5.3.1</version>
  <configuration>
    <!-- other config omitted -->
    <configOptions>
      <oas3>true</oas3>
      <useSpringController>true</useSpringController>
      <useSpringfox>false</useSpringfox>
    </configOptions>
  </configuration>
</plugin>

之后，可能需要添加另一个依赖项作为解决方法，因为插件会将未使用的导入添加到生成的代码中。

<dependency>
  <!-- try to remove this dependency when a new version (5.3.1+) of the openapi-generator plugin is available -->
  <groupId>io.swagger</groupId>
  <artifactId>swagger-annotations</artifactId>
  <version>1.6.3</version>
</dependency>

我正在使用 springdoc-openapi-ui 依赖项。

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.6.3</version>
</dependency>

【讨论】：

5.4.0 似乎解决了未使用的导入问题。