Open API code generator Maven plugin uses old Swagger 2 annotations instead of Swagger 3 annotations

Question

I'm using Open API code generator Maven plugin to generate Open API 3.0 from a file. I'm using this plugin in in my pom.xml:

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

The plugin generates the API without any issues but instead of using Swagger v3 annotations it uses old Swagger annotations. For example parameters are annotated using @ApiParam, instead @Parameter annotation should be used from io.swagger.v3.oas.annotations package:

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

Because of it the latest Swagger UI isn't showing the documentation correctly. When I create an endpoint using swagger.v3 annotations then Swagger UI is working properly.

According to the official website https://openapi-generator.tech/docs/plugins/ , I should include this dependency:

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

But even with this dependency the plugin still generates sources with the old annotations.

How can I force Open API code generator to use Swagger v3 annotations?

Tetanize

Have you found a solution? – Towrope

Answer 1

V3 annotations are not supported at this moment.

You need to override mustache templates.

Check these PRs:
https://github.com/OpenAPITools/openapi-generator/pull/4779
https://github.com/OpenAPITools/openapi-generator/pull/6306

more info:
https://github.com/OpenAPITools/openapi-generator/issues/6108
https://github.com/OpenAPITools/openapi-generator/issues/5803

You can use upgraded templates from PRs above or wait when merged.

Jaymejaymee

Are you aware if there is any progress? It has been open for quite a long time... – Cressida

there is any update on this? – Towrope

the latest release (version 5.3.1) merged this github.com/OpenAPITools/openapi-generator/pull/9775 The Spring code generator now supports v3 annotations -- I am using it on a real-world project -- but I am not 100% satisfied (I still have a couple of template modifications) – Weisberg

Answer 2

Now that version 5.3.1 of the plugin is released, I used the information from https://github.com/OpenAPITools/openapi-generator/pull/9775 and https://github.com/OpenAPITools/openapi-generator/issues/6108 to make it work for me.

I added the three configOptions in the pom.xml:

<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>

After that, it may be necessary to add another dependency as a workaround, because the plugin adds unused imports into the generated code.

<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>

I am using the springdoc-openapi-ui dependency.

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

Ssm

5.4.0 seems to fix the issue with unused imports. – Wingfield