OpenAPITools · jimschubert · Oct 1, 2020 · Sep 30, 2020
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,118 @@
+---
+id: configuration
+title: Configuration Options
+---
+
+Our tooling supports the following types of configuration:
+
+* [global properties](./global-properties.md)
+  - properties with cross-cutting concerns which control generation, but  _don't_ belong to individual generators
+  - Example: `debugSupportingFiles` prints the contents of template data bound to supporting files
+* config options
+  - configuration specific to each individual [generator](./generators/README.md)
+  - these options are susceptible to validation within the defining generator; a config option of the same name across multiple generators may be validated differently in each
+  - NOTE: The CLI accepts config options as "additional properties"
+* additional properties
+  - these are the properties which will be passed to templates
+  - generally used to pass user-defined properties to custom templates
+  - many config options may also be passed as additional properties, however generators will read/modify/rewrite config options
+  - users may pass custom additional properties and use these within templates (e.g. a custom `generatedBy` key with a value of `Jim Schubert` for inclusion in a custom CVS-like header)
+* top-level properties specific to individual tools/plugins used to bootstrap our tooling
+
+## Tool-specific Declarations
+
+The READMEs for the [CLI](https://openapi-generator.tech/docs/usage#generate), [Gradle Plugin](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin), [Maven Plugin](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin), and [SBT Plugin](https://github.com/OpenAPITools/sbt-openapi-generator/blob/master/README.md) may have top-level or tooling specific options which appear to duplicate 'config options' or 'global properties'. Each may also expose user-facing properties slightly differently from the other tools. This may occur due to:
+
+* Conventions used by the underlying tooling
+* Limitations in underlying frameworks which define how properties must be declared
+* Continuation of support for "legacy" invocation patterns
+* Mistakes in documentation and/or contributions (please do [file a bug](https://github.com/OpenAPITools/openapi-generator/issues/new?assignees=&labels=Issue%3A+Bug&template=bug_report.md&title=%5BBUG%5D+Issue+with+options))
+
+Take, for example, the CLI option of `--skip-validate-spec`. This flag sets the value to true with no option to set it to false (the default internally). The maven and gradle plugins allow for the top-level option `skipValidateSpec` to have a value of true or false. The SBT plugin, on the other hand, follows community convention and this property is `openApiSkipValidateSpec`.
+
+_How_ you provide values to options also depends on the tool. OpenAPI Generator supports global properties for [selective generation](https://openapi-generator.tech/docs/customization/#selective-generation) -- such as `apis` -- to have either a blank value or a comma-separated list of selected values. We would define this in CLI as `--global-property apis` or `--global-property apis=Equipment`. In the Gradle Plugin, these properties are set directly as strings:
+
+```
+openApiGenerate {
+    globalProperties = [
+        apis: "",
+        models: "User,Pet"
+    ]
+}
+```
+
+In the Maven plugin, we're limited by XML syntax where `<apis/>` and `<apis></apis>` are treated the same as if the `apis` node was undefined; there's no way to provide an empty string as a default. Instead, we have to extract the global property into its own properties which maintain the two states supported elsewhere (i.e. "all apis" or "select apis"). We have `generateApis` which accepts a boolean and `apisToGenerate` which accepts a comma-separated selection list.
+
+## Discovering Options
+
+Refer to [global properties](./global-properties.md) for a list of available global properties and their usage.
+
+Top-level tooling options are defined in [CLI usage](https://openapi-generator.tech/docs/usage/#generate). Many of these options directly map to camel case options in other tools, but do refer to [plugin documentation](https://openapi-generator.tech/docs/plugins) for full details or plugin-specific differences.
+
+Config options for generators are available in [documentation online](https://openapi-generator.tech/docs/generators). You may also use the CLI to query config options for a target generator using `openapi-generator config-help -g <generator-name>`. For example:
+
+```
+$ openapi-generator config-help -g mysql-schema
+
+CONFIG OPTIONS
+
+	defaultDatabaseName
+	    Default database name for all MySQL queries (Default: )
+
+	identifierNamingConvention
+	    Naming convention of MySQL identifiers(table names and column names). This is not related to database name which is defined by defaultDatabaseName option (Default: original)
+	        original - Do not transform original names
+	        snake_case - Use snake_case names
+
+	jsonDataTypeEnabled
+	    Use special JSON MySQL data type for complex model properties. Requires MySQL version 5.7.8. Generates TEXT data type when disabled (Default: true)
+
+	namedParametersEnabled
+	    Generates model prepared SQLs with named parameters, eg. :petName. Question mark placeholder used when option disabled. (Default: false)
+```
+
+This output provides the name of the configuration option. A set of acceptable values for any constrained values will print as an indented list (e.g. `identifierNamingConvention` above).
+
+Suppose you want to apply snake case naming to mysql schema outputs. Your configuration might resemble the following examples.
+
+**CLI**
+
+```
+openapi-generator -g mysql-schema -o out -i spec.yaml --additional-properties=identifierNamingConvention=snake_case
+```
+
+It may seem like a typo but there are two `=` signs in the above example.
+
+**Maven Plugin**
+
+```
+<execution>
+	<id>mysql-schema</id>
+	<phase>generate-sources</phase>
+	<goals>
+		<goal>generate</goal>
+	</goals>
+	<configuration>
+		<inputSpec>spec.yaml</inputSpec>
+		<generatorName>mysql-schema</generatorName>
+		<configOptions>
+			<identifierNamingConvention>snake_case</identifierNamingConvention>
+		</configOptions>
+		<output>${project.build.directory}/generated-sources/mysql</output>
+	</configuration>
+</execution>
+```
+
+**Gradle Plugin**
+
+```
+openApiGenerate {
+    generatorName = "mysql-schema"
+    inputSpec = "$rootDir/spec.yaml".toString()
+    outputDir = "$buildDir/mysql".toString()
+    configOptions = [
+            identifierNamingConvention: "snake_case"
+    ]
+}
+```
+
diff --git a/docs/generators/ada-server.md b/docs/generators/ada-server.md
@@ -3,6 +3,8 @@ title: Config Options for ada-server
 sidebar_label: ada-server
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/ada.md b/docs/generators/ada.md
@@ -3,6 +3,8 @@ title: Config Options for ada
 sidebar_label: ada
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/android.md b/docs/generators/android.md
@@ -3,6 +3,8 @@ title: Config Options for android
 sidebar_label: android
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/apache2.md b/docs/generators/apache2.md
@@ -3,6 +3,8 @@ title: Config Options for apache2
 sidebar_label: apache2
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/apex.md b/docs/generators/apex.md
@@ -3,6 +3,8 @@ title: Config Options for apex
 sidebar_label: apex
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/asciidoc.md b/docs/generators/asciidoc.md
@@ -3,6 +3,8 @@ title: Config Options for asciidoc
 sidebar_label: asciidoc
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/aspnetcore.md b/docs/generators/aspnetcore.md
@@ -3,6 +3,8 @@ title: Config Options for aspnetcore
 sidebar_label: aspnetcore
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |aspnetCoreVersion|ASP.NET Core version: 3.1, 3.0, 2.2, 2.1, 2.0 (deprecated)| |2.2|

diff --git a/docs/generators/avro-schema.md b/docs/generators/avro-schema.md
@@ -3,6 +3,8 @@ title: Config Options for avro-schema
 sidebar_label: avro-schema
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/bash.md b/docs/generators/bash.md
@@ -3,6 +3,8 @@ title: Config Options for bash
 sidebar_label: bash
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/c.md b/docs/generators/c.md
@@ -3,6 +3,8 @@ title: Config Options for c
 sidebar_label: c
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/clojure.md b/docs/generators/clojure.md
@@ -3,6 +3,8 @@ title: Config Options for clojure
 sidebar_label: clojure
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/cpp-pistache-server.md b/docs/generators/cpp-pistache-server.md
@@ -3,6 +3,8 @@ title: Config Options for cpp-pistache-server
 sidebar_label: cpp-pistache-server
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |addExternalLibs|Add the Possibility to fetch and compile external Libraries needed by this Framework.| |true|

diff --git a/docs/generators/cpp-qt5-client.md b/docs/generators/cpp-qt5-client.md
@@ -3,6 +3,8 @@ title: Config Options for cpp-qt5-client
 sidebar_label: cpp-qt5-client
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/cpp-qt5-qhttpengine-server.md b/docs/generators/cpp-qt5-qhttpengine-server.md
@@ -3,6 +3,8 @@ title: Config Options for cpp-qt5-qhttpengine-server
 sidebar_label: cpp-qt5-qhttpengine-server
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/cpp-restbed-server.md b/docs/generators/cpp-restbed-server.md
@@ -3,6 +3,8 @@ title: Config Options for cpp-restbed-server
 sidebar_label: cpp-restbed-server
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |apiPackage|C++ namespace for apis (convention: name.space.api).| |org.openapitools.server.api|

diff --git a/docs/generators/cpp-restsdk.md b/docs/generators/cpp-restsdk.md
@@ -3,6 +3,8 @@ title: Config Options for cpp-restsdk
 sidebar_label: cpp-restsdk
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |apiPackage|C++ namespace for apis (convention: name.space.api).| |org.openapitools.client.api|

diff --git a/docs/generators/cpp-tizen.md b/docs/generators/cpp-tizen.md
@@ -3,6 +3,8 @@ title: Config Options for cpp-tizen
 sidebar_label: cpp-tizen
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/cpp-ue4.md b/docs/generators/cpp-ue4.md
@@ -3,6 +3,8 @@ title: Config Options for cpp-ue4
 sidebar_label: cpp-ue4
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/csharp-dotnet2.md b/docs/generators/csharp-dotnet2.md
@@ -3,6 +3,8 @@ title: Config Options for csharp-dotnet2
 sidebar_label: csharp-dotnet2
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |clientPackage|C# client package name (convention: Camel.Case).| |Org.OpenAPITools.Client|

diff --git a/docs/generators/csharp-nancyfx.md b/docs/generators/csharp-nancyfx.md
@@ -3,6 +3,8 @@ title: Config Options for csharp-nancyfx
 sidebar_label: csharp-nancyfx
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |asyncServer|Set to true to enable the generation of async routes/endpoints.| |false|

diff --git a/docs/generators/csharp-netcore.md b/docs/generators/csharp-netcore.md
@@ -3,6 +3,8 @@ title: Config Options for csharp-netcore
 sidebar_label: csharp-netcore
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/csharp.md b/docs/generators/csharp.md
@@ -3,6 +3,8 @@ title: Config Options for csharp
 sidebar_label: csharp
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/cwiki.md b/docs/generators/cwiki.md
@@ -3,6 +3,8 @@ title: Config Options for cwiki
 sidebar_label: cwiki
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/dart-dio.md b/docs/generators/dart-dio.md
@@ -3,6 +3,8 @@ title: Config Options for dart-dio
 sidebar_label: dart-dio
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/dart-jaguar.md b/docs/generators/dart-jaguar.md
@@ -3,6 +3,8 @@ title: Config Options for dart-jaguar
 sidebar_label: dart-jaguar
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/dart.md b/docs/generators/dart.md
@@ -3,6 +3,8 @@ title: Config Options for dart
 sidebar_label: dart
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/dynamic-html.md b/docs/generators/dynamic-html.md
@@ -3,6 +3,8 @@ title: Config Options for dynamic-html
 sidebar_label: dynamic-html
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|

diff --git a/docs/generators/eiffel.md b/docs/generators/eiffel.md
@@ -3,6 +3,8 @@ title: Config Options for eiffel
 sidebar_label: eiffel
 ---
 
+These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.
+
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
 |hideGenerationTimestamp|Hides the generation timestamp when files are generated.| |true|