[JAVA jaxrs-spec gen] add option for generating swagger V3 annotations

bin/configs/jaxrs-spec-swagger-annotations.yaml

@@ -0,0 +1,11 @@
+generatorName: jaxrs-spec
+outputDir: samples/server/petstore/jaxrs-spec-swagger-annotations
+inputSpec: modules/openapi-generator/src/test/resources/3_0/jaxrs-spec/petstore-with-fake-endpoints-models-for-testing.yaml
+templateDir: modules/openapi-generator/src/main/resources/JavaJaxRS/spec
+additionalProperties:
+  artifactId: jaxrs-spec-petstore-server
+  serializableModel: "true"
+  hideGenerationTimestamp: "true"
+  implicitHeadersRegex: (api_key|enum_header_string)
+  generateBuilders: "true"
+  useSwaggerAnnotations: "true"

bin/configs/jaxrs-spec-swagger-v3-annotations-jakarta.yaml

@@ -0,0 +1,12 @@
+generatorName: jaxrs-spec
+outputDir: samples/server/petstore/jaxrs-spec-swagger-v3-annotations-jakarta
+inputSpec: modules/openapi-generator/src/test/resources/3_0/jaxrs-spec/petstore-with-fake-endpoints-models-for-testing.yaml
+templateDir: modules/openapi-generator/src/main/resources/JavaJaxRS/spec
+additionalProperties:
+  artifactId: jaxrs-spec-petstore-server-jakarta-swagger-v3
+  serializableModel: "true"
+  hideGenerationTimestamp: "true"
+  implicitHeadersRegex: (api_key|enum_header_string)
+  generateBuilders: "true"
+  useSwaggerV3Annotations: "true"
+  useJakartaEe: "true"

bin/configs/jaxrs-spec-swagger-v3-annotations.yaml

@@ -0,0 +1,11 @@
+generatorName: jaxrs-spec
+outputDir: samples/server/petstore/jaxrs-spec-swagger-v3-annotations
+inputSpec: modules/openapi-generator/src/test/resources/3_0/jaxrs-spec/petstore-with-fake-endpoints-models-for-testing.yaml
+templateDir: modules/openapi-generator/src/main/resources/JavaJaxRS/spec
+additionalProperties:
+  artifactId: jaxrs-spec-petstore-server
+  serializableModel: "true"
+  hideGenerationTimestamp: "true"
+  implicitHeadersRegex: (api_key|enum_header_string)
+  generateBuilders: "true"
+  useSwaggerV3Annotations: "true"

docs/generators/jaxrs-cxf-cdi.md

@@ -84,6 +84,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |useMutiny|Whether to use Smallrye Mutiny instead of CompletionStage for asynchronous computation. Only valid when library is set to quarkus.| |false|
 |useOneOfInterfaces|whether to use a java interface to describe a set of oneOf options, where each option is a class that implements the interface| |false|
 |useSwaggerAnnotations|Whether to generate Swagger annotations.| |true|
+|useSwaggerV3Annotations|Whether to generate Swagger v3 (OpenAPI v3) annotations.| |false|
 |useTags|use tags for creating interface and controller classnames| |false|
 |withXml|whether to include support for application/xml content type and include XML annotations in the model (works with libraries that provide support for JSON and XML)| |false|
 

docs/generators/jaxrs-spec.md

@@ -85,6 +85,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |useMutiny|Whether to use Smallrye Mutiny instead of CompletionStage for asynchronous computation. Only valid when library is set to quarkus.| |false|
 |useOneOfInterfaces|whether to use a java interface to describe a set of oneOf options, where each option is a class that implements the interface| |false|
 |useSwaggerAnnotations|Whether to generate Swagger annotations.| |true|
+|useSwaggerV3Annotations|Whether to generate Swagger v3 (OpenAPI v3) annotations.| |false|
 |useTags|use tags for creating interface and controller classnames| |false|
 |withXml|whether to include support for application/xml content type and include XML annotations in the model (works with libraries that provide support for JSON and XML)| |false|
 

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaJAXRSSpecServerCodegen.java

@@ -42,6 +42,7 @@ public class JavaJAXRSSpecServerCodegen extends AbstractJavaJAXRSServerCodegen {
     public static final String GENERATE_POM = "generatePom";
     public static final String USE_SWAGGER_ANNOTATIONS = "useSwaggerAnnotations";
     public static final String USE_MICROPROFILE_OPENAPI_ANNOTATIONS = "useMicroProfileOpenAPIAnnotations";
+    public static final String USE_SWAGGER_V3_ANNOTATIONS = "useSwaggerV3Annotations";
     public static final String USE_MUTINY = "useMutiny";
     public static final String OPEN_API_SPEC_FILE_LOCATION = "openApiSpecFileLocation";
     public static final String GENERATE_JSON_CREATOR = "generateJsonCreator";
@@ -57,6 +58,7 @@ public class JavaJAXRSSpecServerCodegen extends AbstractJavaJAXRSServerCodegen {
     private boolean returnJbossResponse = false;
     private boolean generatePom = true;
     private boolean useSwaggerAnnotations = true;
+    private boolean useSwaggerV3Annotations = false;
     private boolean useMicroProfileOpenAPIAnnotations = false;
     private boolean useMutiny = false;
 
@@ -133,6 +135,7 @@ public JavaJAXRSSpecServerCodegen() {
         cliOptions.add(CliOption.newBoolean(RETURN_RESPONSE, "Whether generate API interface should return javax.ws.rs.core.Response instead of a deserialized entity. Only useful if interfaceOnly is true.").defaultValue(String.valueOf(returnResponse)));
         cliOptions.add(CliOption.newBoolean(RETURN_JBOSS_RESPONSE, "Whether generate API interface should return `org.jboss.resteasy.reactive.RestResponse` instead of a deserialized entity. This flag cannot be combined with `returnResponse` flag. It requires the flag `interfaceOnly` and `useJakartaEE` set to true, because `org.jboss.resteasy.reactive.RestResponse` was introduced in Quarkus 2.x").defaultValue(String.valueOf(returnJbossResponse)));
         cliOptions.add(CliOption.newBoolean(USE_SWAGGER_ANNOTATIONS, "Whether to generate Swagger annotations.", useSwaggerAnnotations));
+        cliOptions.add(CliOption.newBoolean(USE_SWAGGER_V3_ANNOTATIONS, "Whether to generate Swagger v3 (OpenAPI v3) annotations.", useSwaggerV3Annotations));
         cliOptions.add(CliOption.newBoolean(USE_MICROPROFILE_OPENAPI_ANNOTATIONS, "Whether to generate Microprofile OpenAPI annotations. Only valid when library is set to quarkus.", useMicroProfileOpenAPIAnnotations));
         cliOptions.add(CliOption.newString(OPEN_API_SPEC_FILE_LOCATION, "Location where the file containing the spec will be generated in the output folder. No file generated when set to null or empty string."));
         cliOptions.add(CliOption.newBoolean(SUPPORT_ASYNC, "Wrap responses in CompletionStage type, allowing asynchronous computation (requires JAX-RS 2.1).", supportAsync));
@@ -149,14 +152,28 @@ public void processOpts() {
         convertPropertyToBooleanAndWriteBack(RETURN_JBOSS_RESPONSE, value -> returnJbossResponse = value);
         convertPropertyToBooleanAndWriteBack(SUPPORT_ASYNC, this::setSupportAsync);
         if (QUARKUS_LIBRARY.equals(library) || THORNTAIL_LIBRARY.equals(library) || HELIDON_LIBRARY.equals(library) || OPEN_LIBERTY_LIBRARY.equals(library) || KUMULUZEE_LIBRARY.equals(library)) {
+            // disable Swagger v2 annotations in library modes; MicroProfile or Swagger v3 may be used instead
             useSwaggerAnnotations = false;
         } else {
             convertPropertyToBooleanAndWriteBack(USE_SWAGGER_ANNOTATIONS, value -> useSwaggerAnnotations = value);
         }
+        // Swagger v3 can be used regardless of library
+        convertPropertyToBooleanAndWriteBack(USE_SWAGGER_V3_ANNOTATIONS, value -> useSwaggerV3Annotations = value);
+        // prefer v3 when requested
+        if (useSwaggerV3Annotations) {
+            useSwaggerAnnotations = false;
+        }
         if (KUMULUZEE_LIBRARY.equals(library)) {
             super.setSourceFolder("src/main/java");
         }
 
+        if (useSwaggerAnnotations && useSwaggerV3Annotations) {
+            throw new IllegalArgumentException("Flags 'useSwaggerAnnotations' (v2) and 'useSwaggerV3Annotations' (v3) are mutually exclusive. Please enable only one.");
+        }
+        if (useSwaggerV3Annotations && useMicroProfileOpenAPIAnnotations) {
+            throw new IllegalArgumentException("Flags 'useSwaggerV3Annotations' and 'useMicroProfileOpenAPIAnnotations' are mutually exclusive. Please enable only one.");
+        }
+
         if (QUARKUS_LIBRARY.equals(library)) {
             convertPropertyToBooleanAndWriteBack(USE_MICROPROFILE_OPENAPI_ANNOTATIONS, value -> useMicroProfileOpenAPIAnnotations = value);
         }
@@ -184,6 +201,11 @@ public void processOpts() {
 
         super.processOpts();
 
+        // expose flags to templates
+        additionalProperties.put(USE_SWAGGER_ANNOTATIONS, useSwaggerAnnotations);
+        additionalProperties.put(USE_SWAGGER_V3_ANNOTATIONS, useSwaggerV3Annotations);
+        additionalProperties.put(USE_MICROPROFILE_OPENAPI_ANNOTATIONS, useMicroProfileOpenAPIAnnotations);
+
         supportingFiles.clear(); // Don't need extra files provided by AbstractJAX-RS & Java Codegen
         supportingFiles.add(new SupportingFile("README.mustache", "", "README.md")
                 .doNotOverwrite());

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/api.mustache

@@ -9,6 +9,12 @@ import {{javaxPackage}}.ws.rs.core.Response;
 {{#useSwaggerAnnotations}}
 import io.swagger.annotations.*;
 {{/useSwaggerAnnotations}}
+{{#useSwaggerV3Annotations}}
+import io.swagger.v3.oas.annotations.*;
+import io.swagger.v3.oas.annotations.media.*;
+import io.swagger.v3.oas.annotations.responses.*;
+import io.swagger.v3.oas.annotations.tags.Tag;
+{{/useSwaggerV3Annotations}}
 {{#supportAsync}}
 import java.util.concurrent.CompletionStage;
 import java.util.concurrent.CompletableFuture;
@@ -27,7 +33,8 @@ import {{javaxPackage}}.validation.Valid;{{/useBeanValidation}}
 @Path("{{commonPath}}")
 {{/interfaceOnly}}
 {{#useSwaggerAnnotations}}
-@Api(description = "the {{{baseName}}} API"){{/useSwaggerAnnotations}}{{#hasConsumes}}
+@Api(description = "the {{{baseName}}} API"){{/useSwaggerAnnotations}}{{#useSwaggerV3Annotations}}
+@Tag(name = "{{{baseName}}}"){{/useSwaggerV3Annotations}}{{#hasConsumes}}
 @Consumes({ {{#consumes}}"{{{mediaType}}}"{{^-last}}, {{/-last}}{{/consumes}} }){{/hasConsumes}}{{#hasProduces}}
 @Produces({ {{#produces}}"{{{mediaType}}}"{{^-last}}, {{/-last}}{{/produces}} }){{/hasProduces}}
 {{>generatedAnnotation}}

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/apiInterface.mustache

@@ -26,5 +26,8 @@
     })
     {{/implicitHeadersParams.0}}
     @ApiResponses(value = { {{#responses}}
-        @ApiResponse(code = {{{code}}}, message = "{{{message}}}", response = {{{baseType}}}.class{{#returnContainer}}, responseContainer = "{{{.}}}"{{/returnContainer}}){{^-last}},{{/-last}}{{/responses}} }){{/useSwaggerAnnotations}}
+        @ApiResponse(code = {{{code}}}, message = "{{{message}}}", response = {{{baseType}}}.class{{#returnContainer}}, responseContainer = "{{{.}}}"{{/returnContainer}}){{^-last}},{{/-last}}{{/responses}} }){{/useSwaggerAnnotations}}{{#useSwaggerV3Annotations}}
+    @Operation(summary = "{{{summary}}}", description = "{{{notes}}}")
+    @ApiResponses(value = { {{#responses}}
+        @ApiResponse(responseCode = "{{{code}}}", description = "{{{message}}}"){{^-last}},{{/-last}}{{/responses}} }){{/useSwaggerV3Annotations}}
     {{#supportAsync}}{{>returnAsyncTypeInterface}}{{/supportAsync}}{{^supportAsync}}{{#returnResponse}}Response{{/returnResponse}}{{^returnResponse}}{{>returnTypeInterface}}{{/returnResponse}}{{/supportAsync}} {{nickname}}({{#allParams}}{{>queryParams}}{{>pathParams}}{{>cookieParams}}{{>headerParams}}{{>bodyParams}}{{>formParams}}{{^-last}},{{/-last}}{{/allParams}});

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/apiMethod.mustache

@@ -17,7 +17,11 @@
     {{/implicitHeadersParams.0}}
     @ApiResponses(value = { {{#responses}}
         @ApiResponse(code = {{{code}}}, message = "{{{message}}}", response = {{{baseType}}}.class{{#containerType}}, responseContainer = "{{{.}}}"{{/containerType}}){{^-last}},{{/-last}}{{/responses}}
-    }){{/useSwaggerAnnotations}}
+    }){{/useSwaggerAnnotations}}{{#useSwaggerV3Annotations}}
+    @Operation(summary = "{{{summary}}}", description = "{{{notes}}}")
+    @ApiResponses(value = { {{#responses}}
+        @ApiResponse(responseCode = "{{{code}}}", description = "{{{message}}}"){{^-last}},{{/-last}}{{/responses}}
+    }){{/useSwaggerV3Annotations}}
     public {{#supportAsync}}CompletionStage<{{/supportAsync}}Response{{#supportAsync}}>{{/supportAsync}} {{nickname}}({{#allParams}}{{>queryParams}}{{>pathParams}}{{>cookieParams}}{{>headerParams}}{{>bodyParams}}{{>formParams}}{{^-last}},{{/-last}}{{/allParams}}) {
         return {{#supportAsync}}CompletableFuture.supplyAsync(() -> {{/supportAsync}}Response.ok().entity("magic!").build(){{#supportAsync}}){{/supportAsync}};
     }

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/libraries/quarkus/api.mustache

@@ -14,6 +14,12 @@ import org.jboss.resteasy.annotations.GZIP;
 {{#useSwaggerAnnotations}}
 import io.swagger.annotations.*;
 {{/useSwaggerAnnotations}}
+{{#useSwaggerV3Annotations}}
+import io.swagger.v3.oas.annotations.*;
+import io.swagger.v3.oas.annotations.media.*;
+import io.swagger.v3.oas.annotations.responses.*;
+import io.swagger.v3.oas.annotations.tags.Tag;
+{{/useSwaggerV3Annotations}}
 
 {{#supportAsync}}
 {{#useMutiny}}
@@ -96,7 +102,8 @@ import {{javaxPackage}}.validation.Valid;{{/useBeanValidation}}
         openIdConnectUrl = "{{openIdConnectUrl}}"
     ){{^-last}}, {{/-last}}{{/isOpenId}}{{/authMethods}}
 }){{/hasAuthMethods}}{{/useMicroProfileOpenAPIAnnotations}}{{#useSwaggerAnnotations}}
-@Api(description = "the {{{baseName}}} API"){{/useSwaggerAnnotations}}
+@Api(description = "the {{{baseName}}} API"){{/useSwaggerAnnotations}}{{#useSwaggerV3Annotations}}
+@Tag(name = "{{{baseName}}}"){{/useSwaggerV3Annotations}}
 @Path("{{commonPath}}"){{#hasConsumes}}
 @Consumes({ {{#consumes}}"{{{mediaType}}}"{{^-last}}, {{/-last}}{{/consumes}} }){{/hasConsumes}}{{#hasProduces}}
 @Produces({ {{#produces}}"{{{mediaType}}}"{{^-last}}, {{/-last}}{{/produces}} }){{/hasProduces}}

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/libraries/quarkus/apiInterface.mustache

@@ -19,7 +19,10 @@
     })
     {{/implicitHeadersParams.0}}
     @ApiResponses(value = { {{#responses}}
-        @ApiResponse(code = {{{code}}}, message = "{{{message}}}", response = {{{baseType}}}.class{{#returnContainer}}, responseContainer = "{{{.}}}"{{/returnContainer}}){{^-last}},{{/-last}}{{/responses}} }){{/useSwaggerAnnotations}}{{#useMicroProfileOpenAPIAnnotations}}
+        @ApiResponse(code = {{{code}}}, message = "{{{message}}}", response = {{{baseType}}}.class{{#returnContainer}}, responseContainer = "{{{.}}}"{{/returnContainer}}){{^-last}},{{/-last}}{{/responses}} }){{/useSwaggerAnnotations}}{{#useSwaggerV3Annotations}}
+    @Operation(summary = "{{{summary}}}", description = "{{{notes}}}")
+    @ApiResponses(value = { {{#responses}}
+        @ApiResponse(responseCode = "{{{code}}}", description = "{{{message}}}"){{^-last}},{{/-last}}{{/responses}} }){{/useSwaggerV3Annotations}}{{#useMicroProfileOpenAPIAnnotations}}
     {{#hasAuthMethods}}@org.eclipse.microprofile.openapi.annotations.security.SecurityRequirements(value = {
         {{#authMethods}}{{#isOAuth}}@org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement(
                 name = "{{name}}",

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/libraries/quarkus/apiMethod.mustache

@@ -20,7 +20,11 @@
     {{/implicitHeadersParams.0}}
     @ApiResponses(value = { {{#responses}}
         @ApiResponse(code = {{{code}}}, message = "{{{message}}}", response = {{{baseType}}}.class{{#containerType}}, responseContainer = "{{{.}}}"{{/containerType}}){{^-last}},{{/-last}}{{/responses}}
-    }){{/useSwaggerAnnotations}}{{#useMicroProfileOpenAPIAnnotations}}
+    }){{/useSwaggerAnnotations}}{{#useSwaggerV3Annotations}}
+    @Operation(summary = "{{{summary}}}", description = "{{{notes}}}")
+    @ApiResponses(value = { {{#responses}}
+        @ApiResponse(responseCode = "{{{code}}}", description = "{{{message}}}"){{^-last}},{{/-last}}{{/responses}}
+    }){{/useSwaggerV3Annotations}}{{#useMicroProfileOpenAPIAnnotations}}
     {{#hasAuthMethods}}@org.eclipse.microprofile.openapi.annotations.security.SecurityRequirements(value={
         {{#authMethods}}{{#isOAuth}}@org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement(name = "{{name}}", scopes = { {{#scopes}} "{{scope}}"{{^-last}},{{/-last}} {{/scopes}} }){{^-last}},{{/-last}}{{/isOAuth}}{{^isOAuth}}     @org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement(name = "{{name}}"){{^-last}},{{/-last}}{{/isOAuth}}
    {{/authMethods}} }){{/hasAuthMethods}}

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/libraries/quarkus/pom.mustache

@@ -44,6 +44,9 @@
 {{#useSwaggerAnnotations}}
     <io.swagger.annotations.version>1.6.10</io.swagger.annotations.version>
 {{/useSwaggerAnnotations}}
+{{#useSwaggerV3Annotations}}
+    <io.swagger.v3.annotations.version>2.2.21</io.swagger.v3.annotations.version>
+{{/useSwaggerV3Annotations}}
 {{#useMutiny}}
     <smallrye.rest.client.version>1.2.1</smallrye.rest.client.version>
 {{/useMutiny}}
@@ -118,6 +121,14 @@
         <scope>provided</scope>
      </dependency>
 {{/useSwaggerAnnotations}}
+{{#useSwaggerV3Annotations}}
+     <dependency>
+        <groupId>io.swagger.core.v3</groupId>
+        <artifactId>swagger-annotations</artifactId>
+        <version>${io.swagger.v3.annotations.version}</version>
+        <scope>provided</scope>
+     </dependency>
+{{/useSwaggerV3Annotations}}
 {{#useMutiny}}
     <dependency>
       <groupId>io.smallrye</groupId>

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/pojo.mustache

@@ -1,6 +1,9 @@
 {{#useSwaggerAnnotations}}
 import io.swagger.annotations.*;
 {{/useSwaggerAnnotations}}
+{{#useSwaggerV3Annotations}}
+import io.swagger.v3.oas.annotations.media.Schema;
+{{/useSwaggerV3Annotations}}
 import java.util.Objects;
 {{#jackson}}
 import com.fasterxml.jackson.annotation.JsonProperty;
@@ -21,7 +24,8 @@ import {{javaxPackage}}.xml.bind.annotation.XmlEnumValue;
 {{#discriminator}}{{>typeInfoAnnotation}}{{/discriminator}}{{#description}}/**
  * {{.}}
  **/{{/description}}
-{{#useSwaggerAnnotations}}{{#description}}@ApiModel(description = "{{{.}}}"){{/description}}{{/useSwaggerAnnotations}}{{#useMicroProfileOpenAPIAnnotations}}
+{{#useSwaggerAnnotations}}{{#description}}@ApiModel(description = "{{{.}}}"){{/description}}{{/useSwaggerAnnotations}}{{#useSwaggerV3Annotations}}
+@Schema({{#title}}title="{{{.}}}", {{/title}}{{#description}}description="{{{.}}}"{{/description}}{{^description}}description=""{{/description}}){{/useSwaggerV3Annotations}}{{#useMicroProfileOpenAPIAnnotations}}
 @org.eclipse.microprofile.openapi.annotations.media.Schema({{#title}}title="{{{.}}}", {{/title}}{{#description}}description="{{{.}}}"{{/description}}{{^description}}description=""{{/description}}){{/useMicroProfileOpenAPIAnnotations}}
 {{#jackson}}@JsonTypeName("{{name}}"){{/jackson}}
 {{>generatedAnnotation}}{{>additionalModelTypeAnnotations}}{{>xmlPojoAnnotation}}
@@ -109,7 +113,8 @@ public class {{classname}} {{#parent}}extends {{{.}}}{{/parent}} {{#vendorExtens
       @XmlElement(name="{{baseName}}"{{#required}}, required = {{required}}{{/required}})
   {{/withXml}}
   {{#vendorExtensions.x-extra-annotation}}{{{vendorExtensions.x-extra-annotation}}}{{/vendorExtensions.x-extra-annotation}}{{#useSwaggerAnnotations}}
-  @ApiModelProperty({{#example}}example = "{{{.}}}", {{/example}}{{#required}}required = {{required}}, {{/required}}value = "{{{description}}}"){{/useSwaggerAnnotations}}{{#useMicroProfileOpenAPIAnnotations}}
+  @ApiModelProperty({{#example}}example = "{{{.}}}", {{/example}}{{#required}}required = {{required}}, {{/required}}value = "{{{description}}}"){{/useSwaggerAnnotations}}{{#useSwaggerV3Annotations}}
+  @Schema({{#example}}example = "{{{.}}}", {{/example}}{{#required}}required = {{required}}, {{/required}}description = "{{{description}}}"){{/useSwaggerV3Annotations}}{{#useMicroProfileOpenAPIAnnotations}}
   @org.eclipse.microprofile.openapi.annotations.media.Schema({{#example}}example = "{{{.}}}", {{/example}}{{#required}}required = {{required}}, {{/required}}description = "{{{description}}}"){{/useMicroProfileOpenAPIAnnotations}}
   {{#jackson}}@JsonProperty({{#required}}required = {{required}}, value = {{/required}}"{{baseName}}"){{/jackson}}
   {{#useBeanValidation}}{{>beanValidation}}{{/useBeanValidation}}public {{>beanValidatedType}} {{getter}}() {

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/pom.mustache

@@ -120,6 +120,14 @@
       <version>1.5.3</version>
     </dependency>
     {{/useSwaggerAnnotations}}
+    {{#useSwaggerV3Annotations}}
+    <dependency>
+      <groupId>io.swagger.core.v3</groupId>
+      <artifactId>swagger-annotations</artifactId>
+      <scope>provided</scope>
+      <version>${io.swagger.v3.annotations.version}</version>
+    </dependency>
+    {{/useSwaggerV3Annotations}}
     <!-- @Nullable annotation -->
     <dependency>
         <groupId>com.google.code.findbugs</groupId>
@@ -202,5 +210,8 @@
 {{#openApiNullable}}
     <jackson-databind-nullable-version>0.2.8</jackson-databind-nullable-version>
 {{/openApiNullable}}
+{{#useSwaggerV3Annotations}}
+    <io.swagger.v3.annotations.version>2.2.21</io.swagger.v3.annotations.version>
+{{/useSwaggerV3Annotations}}
   </properties>
 </project>