|
| 1 | +--- |
| 2 | +id: configuration |
| 3 | +title: Configuration Options |
| 4 | +--- |
| 5 | + |
| 6 | +Our tooling supports the following types of configuration: |
| 7 | + |
| 8 | +* [global properties](./global-properties.md) |
| 9 | + - properties with cross-cutting concerns which control generation, but _don't_ belong to individual generators |
| 10 | + - Example: `debugSupportingFiles` prints the contents of template data bound to supporting files |
| 11 | +* config options |
| 12 | + - configuration specific to each individual [generator](./generators/README.md) |
| 13 | + - 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 |
| 14 | + - NOTE: The CLI accepts config options as "additional properties" |
| 15 | +* additional properties |
| 16 | + - these are the properties which will be passed to templates |
| 17 | + - generally used to pass user-defined properties to custom templates |
| 18 | + - many config options may also be passed as additional properties, however generators will read/modify/rewrite config options |
| 19 | + - 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) |
| 20 | +* top-level properties specific to individual tools/plugins used to bootstrap our tooling |
| 21 | + |
| 22 | +## Tool-specific Declarations |
| 23 | + |
| 24 | +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: |
| 25 | + |
| 26 | +* Conventions used by the underlying tooling |
| 27 | +* Limitations in underlying frameworks which define how properties must be declared |
| 28 | +* Continuation of support for "legacy" invocation patterns |
| 29 | +* 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)) |
| 30 | + |
| 31 | +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`. |
| 32 | + |
| 33 | +_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: |
| 34 | + |
| 35 | +``` |
| 36 | +openApiGenerate { |
| 37 | + globalProperties = [ |
| 38 | + apis: "", |
| 39 | + models: "User,Pet" |
| 40 | + ] |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +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. |
| 45 | + |
| 46 | +## Discovering Options |
| 47 | + |
| 48 | +Refer to [global properties](./global-properties.md) for a list of available global properties and their usage. |
| 49 | + |
| 50 | +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. |
| 51 | + |
| 52 | +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: |
| 53 | + |
| 54 | +``` |
| 55 | +$ openapi-generator config-help -g mysql-schema |
| 56 | +
|
| 57 | +CONFIG OPTIONS |
| 58 | +
|
| 59 | + defaultDatabaseName |
| 60 | + Default database name for all MySQL queries (Default: ) |
| 61 | +
|
| 62 | + identifierNamingConvention |
| 63 | + 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) |
| 64 | + original - Do not transform original names |
| 65 | + snake_case - Use snake_case names |
| 66 | +
|
| 67 | + jsonDataTypeEnabled |
| 68 | + Use special JSON MySQL data type for complex model properties. Requires MySQL version 5.7.8. Generates TEXT data type when disabled (Default: true) |
| 69 | +
|
| 70 | + namedParametersEnabled |
| 71 | + Generates model prepared SQLs with named parameters, eg. :petName. Question mark placeholder used when option disabled. (Default: false) |
| 72 | +``` |
| 73 | + |
| 74 | +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). |
| 75 | + |
| 76 | +Suppose you want to apply snake case naming to mysql schema outputs. Your configuration might resemble the following examples. |
| 77 | + |
| 78 | +**CLI** |
| 79 | + |
| 80 | +``` |
| 81 | +openapi-generator -g mysql-schema -o out -i spec.yaml --additional-properties=identifierNamingConvention=snake_case |
| 82 | +``` |
| 83 | + |
| 84 | +It may seem like a typo but there are two `=` signs in the above example. |
| 85 | + |
| 86 | +**Maven Plugin** |
| 87 | + |
| 88 | +``` |
| 89 | +<execution> |
| 90 | + <id>mysql-schema</id> |
| 91 | + <phase>generate-sources</phase> |
| 92 | + <goals> |
| 93 | + <goal>generate</goal> |
| 94 | + </goals> |
| 95 | + <configuration> |
| 96 | + <inputSpec>spec.yaml</inputSpec> |
| 97 | + <generatorName>mysql-schema</generatorName> |
| 98 | + <configOptions> |
| 99 | + <identifierNamingConvention>snake_case</identifierNamingConvention> |
| 100 | + </configOptions> |
| 101 | + <output>${project.build.directory}/generated-sources/mysql</output> |
| 102 | + </configuration> |
| 103 | +</execution> |
| 104 | +``` |
| 105 | + |
| 106 | +**Gradle Plugin** |
| 107 | + |
| 108 | +``` |
| 109 | +openApiGenerate { |
| 110 | + generatorName = "mysql-schema" |
| 111 | + inputSpec = "$rootDir/spec.yaml".toString() |
| 112 | + outputDir = "$buildDir/mysql".toString() |
| 113 | + configOptions = [ |
| 114 | + identifierNamingConvention: "snake_case" |
| 115 | + ] |
| 116 | +} |
| 117 | +``` |
| 118 | + |
0 commit comments