Merge branch 'OpenAPITools:master' into master

Author: Chrimle

.github/workflows/samples-jaxrs.yaml

@@ -34,6 +34,9 @@ jobs:
           - samples/server/petstore/jaxrs-cxf-cdi
           - samples/server/petstore/jaxrs-cxf-non-spring-app
           - samples/server/petstore/jaxrs-spec-microprofile-openapi-annotations
+          - samples/server/petstore/jaxrs-spec-swagger-annotations
+          - samples/server/petstore/jaxrs-spec-swagger-v3-annotations-jakarta
+          - samples/server/petstore/jaxrs-spec-swagger-v3-annotations
     steps:
       - uses: actions/checkout@v5
       - uses: actions/setup-java@v5

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/java/org/openapitools/codegen/languages/PhpNextgenClientCodegen.java

@@ -188,6 +188,7 @@ public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<Mo
         for (CodegenOperation operation : operations.getOperation()) {
             Set<String> phpReturnTypeOptions = new LinkedHashSet<>();
             Set<String> docReturnTypeOptions = new LinkedHashSet<>();
+            boolean hasEmptyResponse = false;
 
             for (CodegenResponse response : operation.responses) {
                 if (response.dataType != null) {
@@ -200,6 +201,8 @@ public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<Mo
 
                     phpReturnTypeOptions.add(returnType);
                     docReturnTypeOptions.add(response.dataType);
+                } else {
+                    hasEmptyResponse = true;
                 }
             }
 
@@ -208,9 +211,16 @@ public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<Mo
                 operation.vendorExtensions.putIfAbsent("x-php-return-type", "void");
                 operation.vendorExtensions.putIfAbsent("x-php-doc-return-type", "void");
             } else {
+                String phpReturnType = String.join("|", phpReturnTypeOptions);
+                String docReturnType = String.join("|", docReturnTypeOptions);
+                if (hasEmptyResponse) {
+                    phpReturnType = "?" + phpReturnType;
+                    docReturnType = docReturnType + "|null";
+                }
+
                 operation.vendorExtensions.putIfAbsent("x-php-return-type-is-void", false);
-                operation.vendorExtensions.putIfAbsent("x-php-return-type", String.join("|", phpReturnTypeOptions));
-                operation.vendorExtensions.putIfAbsent("x-php-doc-return-type", String.join("|", docReturnTypeOptions));
+                operation.vendorExtensions.putIfAbsent("x-php-return-type", phpReturnType);
+                operation.vendorExtensions.putIfAbsent("x-php-doc-return-type", docReturnType);
             }
 
             for (CodegenParameter param : operation.allParams) {

modules/openapi-generator/src/main/resources/C-libcurl/api-body.mustache

@@ -188,15 +188,6 @@ end:
 
     localVarPath = strReplace(localVarPath, localVarToReplace_{{paramName}}, {{^isEnum}}{{paramName}}{{/isEnum}}{{#isEnum}}{{{operationId}}}_{{enumName}}_ToString({{paramName}}){{/isEnum}});
     {{/isString}}
-    {{#isUuid}}
-    if({{paramName}} == NULL) {
-        goto end;
-    }
-    char* localVarToReplace_{{paramName}} = malloc(sizeOfPathParams_{{paramName}});
-    sprintf(localVarToReplace_{{paramName}}, "{%s}", "{{baseName}}");
-
-    localVarPath = strReplace(localVarPath, localVarToReplace_{{paramName}}, {{paramName}});
-    {{/isUuid}}
     {{/pathParams}}
 
 

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;
@@ -23,11 +29,9 @@ import {{javaxPackage}}.validation.Valid;{{/useBeanValidation}}
 /**
 * Represents a collection of functions to interact with the API endpoints.
 */
-{{^interfaceOnly}}
-@Path("{{commonPath}}")
-{{/interfaceOnly}}
-{{#useSwaggerAnnotations}}
-@Api(description = "the {{{baseName}}} API"){{/useSwaggerAnnotations}}{{#hasConsumes}}
+@Path("{{commonPath}}"){{#useSwaggerAnnotations}}
+@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}}