[docs] Update site with global properties list and usage explanation

Author: jimschubert

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:
 

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/usage.md

@@ -260,14 +260,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>...]
@@ -323,10 +323,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).
@@ -342,11 +338,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.
@@ -357,6 +353,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
 

website/docusaurus.config.js

@@ -46,7 +46,7 @@ const docusaurusConfig = {
       },
 
       links: [
-        {to: 'docs/installation', label: 'Install'},
+        {to: 'docs/installation', label: 'Getting Started'},
         {to: 'docs/generators', label: 'Generators'},
         {to: 'docs/roadmap', label: 'Roadmap'},
         {to: "docs/faq", label: "FAQ" },

website/sidebars.js

@@ -5,7 +5,8 @@ module.exports = {
       'installation',
       'plugins',
       'online',
-      'usage'
+      'usage',
+      'globals'
     ],
     'Extending': [
       'templating',