Merge branch 'master' into ensures

* master:
  Update Generate.java (#6515)
  Undo PR #6451 (#6514)
  Minor enhancement to Python client generator's code format (#6510)
  [python-experimental] Quicken package loading (#6437)
  [Python][Client] Fix delimiter collision issue #5981 (#6451)
  [Java][Jersey2] add petstore integration tests (#6508)
  UE4 client generator fixes (#6438)
  Fix docs typos (#6478)
  [php-laravel] Show required PHP version in docs (#6502)
  [php-lumen] Show required PHP version in docs (#6501)
  [Java][Jersey2] Fix typo and script, Log enhancements, HTTP signature, deserialization (#6476)
  Remove deprecations 5.0 (#6060)

CI/samples.ci/client/petstore/java/test-manual/jersey2-java8/JSONComposedSchemaTest.java

@@ -0,0 +1,68 @@
+package org.openapitools.client;
+
+import org.openapitools.client.model.Mammal;
+import org.openapitools.client.model.AppleReq;
+import org.openapitools.client.model.BananaReq;
+import org.openapitools.client.model.FruitReq;
+import org.openapitools.client.model.BasquePig;
+import org.openapitools.client.model.Pig;
+import org.openapitools.client.model.Whale;
+import org.openapitools.client.model.Zebra;
+import java.lang.Exception;
+
+import org.junit.*;
+import static org.junit.Assert.*;
+
+
+public class JSONComposedSchemaTest {
+    JSON json = null;
+    Mammal mammal = null;
+
+    @Before
+    public void setup() {
+        json = new JSON();
+        mammal = new Mammal();
+    }
+
+    /**
+     * Validate a oneOf schema can be deserialized into the expected class.
+     * The oneOf schema does not have a discriminator. 
+     */
+    @Test
+    public void testOneOfSchemaWithoutDiscriminator() throws Exception {
+        // BananaReq and AppleReq have explicitly defined properties that are different by name.
+        // There is no discriminator property.
+        String str = "{ \"cultivar\": \"golden delicious\", \"mealy\": false }";
+        FruitReq o = json.getContext(null).readValue(str, FruitReq.class);
+        assertTrue(o.getActualInstance() instanceof AppleReq);
+    }
+
+    /**
+     * Validate a oneOf schema can be deserialized into the expected class.
+     * The oneOf schema has a discriminator. 
+     */
+    @Test
+    public void testOneOfSchemaWithDiscriminator() throws Exception {
+        // Mammal can be one of whale, pig and zebra.
+        // pig has sub-classes.
+        String str = "{ \"className\": \"whale\", \"hasBaleen\": true, \"hasTeeth\": false }";
+        /*
+        DISABLING unit test for now until ambiguity of discriminator is resolved.
+        
+        // Note that the 'zebra' schema does not have any explicit property defined AND
+        // it has additionalProperties: true. Hence without a discriminator the above
+        // JSON payload would match both 'whale' and 'zebra'. This is because the 'hasBaleen'
+        // and 'hasTeeth' would be considered additional (undeclared) properties for 'zebra'.
+        Mammal o = json.getContext(null).readValue(str, Mammal.class);
+        assertTrue(o.getActualInstance() instanceof Whale);
+
+        str = "{ \"className\": \"zebra\" }";
+        o = json.getContext(null).readValue(str, Mammal.class);
+        assertTrue(o.getActualInstance() instanceof Zebra);
+
+        str = "{ \"className\": \"BasquePig\" }";
+        o = json.getContext(null).readValue(str, Mammal.class);
+        assertTrue(o.getActualInstance() instanceof BasquePig);
+        */
+    }
+}

bin/configs/java-jersey2-8.yaml

@@ -1,7 +1,7 @@
 generatorName: java
 outputDir: samples/openapi3/client/petstore/java/jersey2-java8
 library: jersey2
-inputSpec: modules/openapi-generator/src/test/resources/2_0/petstore-with-fake-endpoints-models-for-testing.yaml
+inputSpec: modules/openapi-generator/src/test/resources/3_0/python-experimental/petstore-with-fake-endpoints-models-for-testing-with-http-signature.yaml
 additionalProperties:
   artifactId: petstore-openapi3-jersey2-java8
   hideGenerationTimestamp: "true"

docs/customization.md

@@ -90,7 +90,8 @@ You can use this as additional dependency of the `openapi-generator-maven-plugin
 If you publish your artifact to a distant maven repository, do not forget to add this repository as `pluginRepository` for your project.
 
 ## Selective generation
-You may not want to generate *all* models in your project.  Likewise you may want just one or two apis to be written.  If that's the case, you can use system properties to control the output:
+
+You may not want to generate *all* models in your project. Likewise, you may want just one or two apis to be written.  If that's the case, you can use system properties or [global properties](./global-properties.md) to control the output.
 
 The default is generate *everything* supported by the specific library.  Once you enable a feature, it will restrict the contents generated:
 
@@ -142,7 +143,13 @@ When using selective generation, _only_ the templates needed for the specific ge
 To skip models defined as the form parameters in "requestBody", please use `skipFormModel` (default to false) (this option is introduced at v3.2.2)
 
 ```sh
-java -DskipFormModel=true
+java -DskipFormModel=true <path to jar> generate …
+```
+
+or
+
+```sh
+java <path to jar> generate --global-property skipFormModel=true …
 ```
 
 This option will be helpful to skip model generation due to the form parameter, which is defined differently in OAS3 as there's no form parameter in OAS3

docs/faq-contributing.md

@@ -45,9 +45,9 @@ Please refer to http://rypress.com/tutorials/git/rebasing, or follow the steps b
 
 (To setup `upstream` pointing to the official repo, please run `git remote add upstream  https://github.com/openapitools/openapi-generator.git`)
 
-## How can I update commits that are not linked to my Github account?
+## How can I update commits that are not linked to my GitHub account?
 
-Please refer to https://stackoverflow.com/questions/3042437/how-to-change-the-commit-author-for-one-specific-commit or you can simply add the email address in the commit as your secondary email address in your Github account.
+Please refer to https://stackoverflow.com/questions/3042437/how-to-change-the-commit-author-for-one-specific-commit or you can simply add the email address in the commit as your secondary email address in your GitHub account.
 
 ## Any useful git tips to share?
 

docs/global-properties.md

@@ -0,0 +1,43 @@
+---
+id: globals
+title: Global Properties
+---
+
+## Available Global Properties
+
+| Property | Description | Acceptable value |
+| -------- | ------------| ---------------- |
+| debugOpenAPI | Dumps JSON formatted and fully parsed OpenAPI document during generation | none |
+| debugModels | Dumps JSON formatted template-bound model information during generation | none |
+| debugOperations | Dumps JSON formatted template-bound operation information during generation | none |
+| debugSupportingFiles | Dumps JSON formatted Supporting File information during generation | none |
+| verbose | Defines the verbosity | `true` or `false` |
+| generateAliasAsModel | Defines whether primitive types defined at the model/schema level will be wrapped in a model | `true` or `false` |
+| org.openapitools.codegen.utils.oncelogger.enabled | Enable/disable the "OnceLogger" which reduces noise for select repeated logs | `true` or `false` |
+| supportingFiles | Allows the user to define which supporting files will be generated. Prefer using the more robust `.openapi-generator-ignore`. | no value, or a comma-separated string of file names |
+| models | Allows the user to define which models will be generated. Prefer using the more robust `.openapi-generator-ignore`. | no value, or a comma-separated string of model names |
+| apis | Allows the user to define which apis will be generated. Prefer using the more robust `.openapi-generator-ignore`. | no value, or a comma-separated string of api names |
+| apiDocs | Allows the user to define if api docs will be generated. Prefer using the more robust `.openapi-generator-ignore`. | `true` or `false` |
+| modelDocs | Allows the user to define if model docs will be generated. Prefer using the more robust `.openapi-generator-ignore`. | `true` or `false` |
+| apiTests | Allows the user to define if api tests will be generated. Prefer using the more robust `.openapi-generator-ignore`. | `true` or `false` |
+| modelTests | Allows the user to define if model tests will be generated. Prefer using the more robust `.openapi-generator-ignore`. | `true` or `false` |
+| withXml | Allows the user to control support of XML generated constructs, where supported | none |
+
+
+## Note on Global Property declaration
+
+There are _two ways_ to provide selective generation properties or "global properties". First, these can be passed as Java System Properties. Second, these can be passed via the global property tooling option (`--global-property` in CLI and `globalProperty` in Maven and Gradle configurations). This differentiation is new in version 5.0 with the removal of the `-D` CLI option and the renaming of `systemProperties`. If you're upgrading to OpenAPI Generator 5.0+
+
+While the examples seen in [Customization](./customization.md) use the Java System Property syntax, keep in mind that the following are equivalent:
+
+```sh
+java -Dmodels {jar} generate {opts}
+```
+
+and
+
+```sh
+java {jar} generate {opts} --global-property=models
+```
+
+Why the two differing ways to provide the same properties? We previously accepted a `-D` tooling option which resembled Java System Property declaration. In older versions of OpenAPI Generator, the option modified the SystemProperties collection directly and was truly a "system property". This option changed during the 4.x release in an effort to make OpenAPI Generator thread-safe and isolate its configuration via thread locals. We no longer mutate System Properties. In the 4.x release and earlier, specifying the tooling `-D` option with system properties intended for other tools like swagger-parser rather than passing them as true Java System Properties would lead to unexpected behavior for the user; if our tool set the system property _after_ invoking certain code, it would seem to the user like Java System Properties weren't working! 

docs/installation.md

@@ -8,11 +8,11 @@ Installing OpenAPI Generator's CLI tool allows users to generate all available g
 
 Some of the following are cross-platform options and some are not, these are called out where possible.
 
-## NPM
+## npm
 
 > **Platform(s)**: Linux, macOS, Windows
 
-The [NPM package wrapper](https://github.com/openapitools/openapi-generator-cli) is cross-platform wrapper around the .jar artifact. It works by providing a CLI wrapper atop the JAR's command line options. This gives a simple interface layer which normalizes usage of the command line across operating systems, removing some differences in how options or switches are passed to the tool (depending on OS).
+The [npm package wrapper](https://github.com/openapitools/openapi-generator-cli) is cross-platform wrapper around the .jar artifact. It works by providing a CLI wrapper atop the JAR's command line options. This gives a simple interface layer which normalizes usage of the command line across operating systems, removing some differences in how options or switches are passed to the tool (depending on OS).
 **Install** the latest version of the tool globally, exposing the CLI on the command line:
 
 ```bash

docs/integration.md

@@ -2,7 +2,7 @@
 id: integrations
 title: Workflow Integrations
 ---
-## Workflow Integration (Maven, Github, CI/CD)
+## Workflow Integration (Maven, GitHub, CI/CD)
 
 ### Gradle Integration
 
@@ -39,7 +39,7 @@ To push the auto-generated SDK to GitHub, we provide `git_push.sh` to streamline
  -i modules/openapi-generator/src/test/resources/2_0/petstore.json -g perl \
  --git-user-id "wing328" \
  --git-repo-id "petstore-perl" \
- --release-note "Github integration demo" \
+ --release-note "GitHub integration demo" \
  -o /var/tmp/perl/petstore
 ```
  3) Push the SDK to GitHub

docs/usage.md

@@ -261,14 +261,14 @@ SYNOPSIS
                 [(-a <authorization> | --auth <authorization>)]
                 [--api-name-suffix <api name suffix>] [--api-package <api package>]
                 [--artifact-id <artifact id>] [--artifact-version <artifact version>]
-                [(-c <configuration file> | --config <configuration file>)]
-                [-D <system properties>...] [--dry-run]
+                [(-c <configuration file> | --config <configuration file>)] [--dry-run]
                 [(-e <templating engine> | --engine <templating engine>)]
                 [--enable-post-process-file]
                 [(-g <generator name> | --generator-name <generator name>)]
                 [--generate-alias-as-model] [--git-host <git host>]
                 [--git-repo-id <git repo id>] [--git-user-id <git user id>]
-                [--group-id <group id>] [--http-user-agent <http user agent>]
+                [--global-property <global properties>...] [--group-id <group id>]
+                [--http-user-agent <http user agent>]
                 (-i <spec file> | --input-spec <spec file>)
                 [--ignore-file-override <ignore file override location>]
                 [--import-mappings <import mappings>...]
@@ -324,10 +324,6 @@ OPTIONS
             different for each language. Run config-help -g {generator name}
             command for language-specific config options.
 
-        -D <system properties>
-            sets specified system properties in the format of
-            name=value,name=value (or multiple options, each with name=value)
-
         --dry-run
             Try things out and report on potential changes (without actually
             making changes).
@@ -343,11 +339,11 @@ OPTIONS
 
         --generate-alias-as-model
             Generate model implementation for aliases to map and array schemas.
-            An 'alias' is an array, map, or list which is defined inline in a 
-            OpenAPI document and becomes a model in the generated code.
-            A 'map' schema is an object that can have undeclared properties,
-            i.e. the 'additionalproperties' attribute is set on that object.
-            An 'array' schema is a list of sub schemas in a OAS document.
+            An 'alias' is an array, map, or list which is defined inline in a
+            OpenAPI document and becomes a model in the generated code. A 'map'
+            schema is an object that can have undeclared properties, i.e. the
+            'additionalproperties' attribute is set on that object. An 'array'
+            schema is a list of sub schemas in a OAS document
 
         --git-host <git host>
             Git host, e.g. gitlab.com.
@@ -358,6 +354,11 @@ OPTIONS
         --git-user-id <git user id>
             Git user ID, e.g. openapitools.
 
+        --global-property <global properties>
+            sets specified global properties (previously called 'system
+            properties') in the format of name=value,name=value (or multiple
+            options, each with name=value)
+
         --group-id <group id>
             groupId in generated pom.xml
 

modules/openapi-generator-cli/src/main/java/org/openapitools/codegen/cmd/Generate.java

@@ -71,9 +71,8 @@ public class Generate extends OpenApiGeneratorCommand {
                     + "Pass in a URL-encoded string of name:header with a comma separating multiple values")
     private String auth;
 
-    // TODO: Remove -D short option in 5.0
     @Option(
-            name = {"-D", "--global-property"},
+            name = {"--global-property"},
             title = "global properties",
             description = "sets specified global properties (previously called 'system properties') in "
                     + "the format of name=value,name=value (or multiple options, each with name=value)")
@@ -231,7 +230,7 @@ public class Generate extends OpenApiGeneratorCommand {
     @Option(name = {"--log-to-stderr"},
             title = "Log to STDERR",
             description = "write all log messages (not just errors) to STDOUT."
-                    + " Useful for piping the JSON output of debug options (e.g. `-DdebugOperations`) to an external parser directly while testing a generator.")
+                    + " Useful for piping the JSON output of debug options (e.g. `--global-property debugOperations`) to an external parser directly while testing a generator.")
     private Boolean logToStderr;
 
     @Option(name = {"--enable-post-process-file"}, title = "enable post-process file", description = CodegenConstants.ENABLE_POST_PROCESS_FILE_DESC)
@@ -408,7 +407,6 @@ public void execute() {
         }
 
         if (globalProperties != null && !globalProperties.isEmpty()) {
-            System.err.println("[DEPRECATED] -D arguments after 'generate' are application arguments and not Java System Properties, please consider changing to --global-property, apply your system properties to JAVA_OPTS, or move the -D arguments before the jar option.");
             applyGlobalPropertiesKvpList(globalProperties, configurator);
         }
         applyInstantiationTypesKvpList(instantiationTypes, configurator);